Developer Documentation

Every Wallcraft widget is simply a local folder containing 4 core code files, plus optional dedicated media assets:

Here is a complete, minimal "Live Clock" widget:

Because Wallcraft runs as a native background desktop canvas behind Windows desktop icons (WorkerW / Progman layer), standard global browser shortcuts like F12 are not intercepted by the desktop wallpaper window. Use the following proven workflow to develop and debug:

1. 1. Local Layout Preview: Open the downloaded clock’s preview.html in a browser. For your own widget, provide a preview harness that loads CSS/JS and calls init; it cannot emulate native SDK services. Press F12 to open DevTools, inspect DOM/CSS layout, and debug your JavaScript logic with breakpoints and live network tabs.
2. 2. In-App Terminal Logging: When testing your imported widget inside Wallcraft, launch the application from the command line (npm start or Developer build). All console.log, console.warn, and console.error messages inside the sandboxed iframe are forwarded via wc:sandbox-log and output to the host terminal prefixed with [Widget:<widget-id>].
3. 3. Live Reload via Settings: Import your widget folder via Settings → Modules & Widgets → "Import Folder". After editing your local files, toggle the widget off and back on in Settings to instantly reload the iframe without restarting Wallcraft.

Sandboxed community widgets communicate with the WallCraft host through asynchronous JSON messages over the HTML5 postMessage bridge.

The manifest.json file defines your widget identity, layout requirements, dynamic settings form, and theme wrapper.

Wallcraft features an intelligent dual-media detection engine (detectWidgetMedia in widget-manager.js) for both built-in and community extensions. Developers can supply a dedicated tile icon for the Modules & Widgets catalog as well as high-definition preview images for the marketplace, completely independently:

• Dedicated Tile Icon (manifest.icon / icon.png): Rendered on the widget card/tile inside Wallcraft Settings. The runtime checks manifest.icon or manifest.iconImage first; if omitted, it automatically scans the widget folder for icon.png, icon.webp, icon.svg, icon.jpg, or icon.jpeg. If no icon file is found, Wallcraft gracefully falls back to the preview image, or displays an elegant two-letter uppercase monogram over an algorithmic 135-degree procedural gradient.
• Fullscreen Preview (manifest.previewImage / preview.webp): Used for full-resolution showcase previews, marketplace detail modals, and catalog cards. The runtime checks manifest.previewImage or manifest.previewUrl; if omitted, it automatically scans the widget folder for preview.webp, preview.png, preview.jpg, preview.jpeg, or preview.svg.
• Zero-Config Auto-Discovery: Declaring icon or previewImage in manifest.json is entirely optional. Simply dropping icon.png and preview.webp into your widget root folder enables instant auto-detection upon folder or .zip import.

Wallcraft divides the user desktop into a 24 horizontal columns × 24 vertical rows grid. When widgets are dragged, they magnetically snap to grid intersections and center axes.

Every widget script exports an object containing the core lifecycle hooks. Wallcraft triggers these methods during initialization, settings change, and application shutdown:

When users click the gear icon on your widget, Wallcraft automatically renders an acrylic modal form based on your configSchema array. When saved, the updated configuration object is passed to your update(config) method.

The reorder type renders sortable cards with up/down arrows. When reordered by the user, the update(config) lifecycle hook receives a sorted array of string IDs:

Wallcraft provides a centralized Design Token Layer. By using semantic CSS variables instead of hardcoded hex values, your widget automatically adapts to the selected frame option: 10 built-in themes (including Liquid Glass, Flat Dark, and Caldera) or Zero-Wrapper.

WallCraft includes 10 frame themes and a frameless mode. The table lists their default accents and card/button radii from the theme token definitions. Flat Dark uses an opaque surface without blur or shadows. Liquid Glass uses a translucent, separately filtered glass layer; Acrylic Blur also uses backdrop blur. Users can customize fonts, colors and radii in Settings:

Users can tailor any wrapper theme directly in Wallcraft Settings → Theme Tokens with immediate live preview:

• Primary & Secondary Typography: Independently select from 13 font options.
• 2-Tier Accent Color Hierarchy: Override --theme-accent (primary) and --theme-accent-secondary (glow/badges).
• Corner Curvature: Sliders for Card Border Radius (0px to 64px) and Button / Pill Radius (0px to 32px).
• Live RPC Synchronization: Changes are immediately broadcasted to all active widget iframes via wc:theme-update.

Community widgets are standalone .zip archives. WallCraft passes the selected interface language to your widget through window.WallCraft.language and window.WallCraft.onLanguageChange. Each widget supplies its own translations.

Widgets with the "system-stats" permission can query real-time hardware telemetry including CPU utilization, core temperature, RAM usage, GPU load, GPU temperature (via NVIDIA NVML / AMD ADL), and system uptime.

Wallcraft exposes Windows WASAPI Core Audio controls directly to sandboxed widgets through the asynchronous window.WallCraft.audio bridge.

Widgets with the "media" permission can interface with Windows System Media Transport Controls (SMTC) to read metadata from Spotify, Chrome, Edge, and Apple Music, as well as trigger playback controls.

Widgets with the "discord" permission connect directly to the Discord Gateway RPC client on Windows, allowing you to create live voice channel overlays and voice activity indicators on the desktop.

Launch installed Windows software and extract native high-resolution icons directly from executable (.exe) and shortcut (.lnk) files:

Access Windows native file picker dialogs, retrieve current system wallpaper path. These calls are mediated by the host; they do not grant direct filesystem access:

Write plain text programmatically to the Windows system clipboard. While community widgets use synthetic keyboard shortcuts (Ctrl+C, Ctrl+V) and postMessage clipboard signals transparently, privileged host components and settings windows can trigger clipboard writes directly:

Used primarily by Wallcraft settings and troubleshooting panels to inspect GPU capabilities, memory limits, and submit in-app developer reports:

Powers the Wallcraft Settings UI (Modules & Widgets tab) to catalog installed widgets, safely read source files, open the community widgets directory, import packages, and delete widgets:

Due to iframe sandbox policies, widgets cannot spawn unconstrained popups. Instead, Wallcraft provides a sleek, acrylic desktop modal dialog triggered via a single asynchronous promise call:

Wallcraft routes native Windows mouse and keyboard events directly into the sandboxed iframe:

• Pointer Simulation: Desktop clicks are translated to PointerEvent inside the sandbox.
• Keyboard Hook: Focusing an <input> or <textarea> activates a transparent Win32 keyboard hook for typing, Backspace, Enter, and Arrow keys.
• Clipboard Sync: Ctrl+C, Ctrl+V, and Ctrl+X sync seamlessly with the Windows clipboard over postMessage.

HTML5 sandboxed iframes without allow-same-origin cannot use normal origin-backed browser storage. WallCraft installs an In-Memory Storage Shim for localStorage and sessionStorage. Both use the same Map within the current iframe instance; values are lost when the widget reloads or its iframe is recreated. This is temporary storage, not disk-backed persistence.

For persistent preferences, declare fields with configSchema in manifest.json and have the user save them through the Settings form. Declaring the schema or calling selectAppOrFolder() alone does not save values. The public sandbox SDK has no config-write method; changing a local variable, WallCraft.config or the storage shim does not update saved Settings.

To prepare a widget ZIP for local sharing or import:

1. Package Structure: Ensure manifest.json is located at the root of the archive (not nested in an extra subfolder).
2. Media Assets: Include a dedicated tile icon (icon.png or icon.webp, 1:1 square ratio, recommended 128×128 or 256×256 px) and a high-resolution preview image (preview.webp or preview.png, 16:9 ratio, recommended 1280×720 or 1920×1080 px) at the archive root for instant visual recognition in the Wallcraft catalog.
3. Flat Compression: Compress the folder contents into a standard .zip file (e.g. my-widget.zip).
4. Local Validation: Test extraction by importing the .zip via Wallcraft Settings -> Modules & Widgets -> "Import Package".

1. Publication identity: Open the in-app Community Hub submission modal and select your own saved shader, widget or preset. Display names may repeat across all types; catalog IDs must be unique across types, ignoring case. Creator Studio generates a publication ID independently of the title. For updates, select the same saved local source to retain that ID, even when renaming the item. Save an unsaved creation locally before its first submission if you plan to update it; an unsaved draft ID is retained only while the modal stays open. Hub downloads cannot be re-published.
2. Export formats: Use Export Package in the submission modal after filling in metadata. Widgets export as .zip, shaders as .json, and presets as .wallcraft-preset.json. Only widget ZIPs use a root manifest.json. Keep the generated ID; do not derive it from the display name or export the original local source instead.
3. Submit: Use Submit PR to Hub with a classic GitHub token with public_repo scope, or use the modal’s Git commands inside a local clone of your fork after installing Git/GitHub CLI and running gh auth login. For manual submission, extract the widget ZIP contents into widgets/<publication-id>/; save shader JSON as shaders/<publication-id>.json and preset JSON as presets/<publication-id>.wallcraft-preset.json. Preserve manifest.id, instanceName and asset paths. A JSON payload containing widgetFiles is not a widget manifest; use the exported ZIP.
4. Validation and dependencies: Widget manifest IDs and shader/preset payload IDs must match their catalog IDs. Widget pack child IDs must also be unique and must not collide with catalog items or built-in widget IDs. Publish custom widgets and shaders used by a preset first, then export the preset from the submission modal so known publication IDs are used in its references. Presets do not embed those widget packages. Maintainers regenerate catalog-v2.json with commit pins and SHA-256 hashes after reviewing source changes; contributors do not hand-edit hashes.

Wallcraft provides a resilient multi-monitor hardware identity engine (monitor-identity.js) that decouples transient OS display indexes from physical monitors.

Core Architectural Features

• Persistent Hardware Identity: Resolves displays by EDID descriptors, PnP manufacturer IDs, physical resolution, and scale factor. Disconnecting or reconnecting a monitor preserves saved positions and layouts without corruption.
• Independent Per-Monitor Customization: Each physical monitor can run its own independent live wallpaper (different GLSL shaders, videos, image slideshows, or solid colors), its own independent set of widgets on separate 24×24 magnetic grids, and individual theme token overrides.
• Display Identify Overlays: The showDisplayIdentifyOverlays service flashes high-contrast monitor numbers directly onto each physical screen, allowing users to immediately identify which display is being configured in Settings.
• Multi-Profile Management: Create and switch between up to 10 persistent user profiles with inline rename, duplicate, and delete actions. Profiles can be exported and shared as .json preset files.

In addition to standard desktop-level widgets behind application windows, Wallcraft supports Always-on-Top Pinned Overlays that float above games, full-screen apps, and browser windows.

How Pinned Overlays Operate

• WS_EX_TOPMOST Management: Pinned widgets run inside specialized transparent overlay windows (pinnedOverlayWindows).
• Foreground WinEvent Hook: A native EVENT_SYSTEM_FOREGROUND hook automatically re-asserts pinned widgets at the head of the HWND_TOPMOST band whenever games, browsers, or external windows gain focus.
• Transparent Click-Through Hit Testing: When the mouse is outside a pinned widget's boundary, the window applies setIgnoreMouseEvents(true): clicks pass completely through to the game or application below. When the cursor enters widget bounds or an interactive modal opens, setIgnoreMouseEvents(false) is dynamically engaged for instant interactivity.

Wallcraft runs on a high-performance WebGL 2.0 (with WebGL 1.0 fallback) fullscreen quad. Your custom GLSL fragment shader paints directly to the GPU at 60/144+ FPS.

Standalone shader capture uses desktop getUserMedia, an AudioContext and AnalyserNode with fftSize = 64. A requestAnimationFrame loop reads 32 FFT bins and divides byte magnitudes by 255. Capture availability and latency depend on the device and runtime; this path does not promise a worker or zero latency. A running Audio Visualizer can feed the shader through a different spectrum mapping.

Access individual frequency bands in your shader with u_audio_spectrum[i] (where i is 0 to 31), or use convenient grouped bands: u_audio_bass, u_audio_mid, and u_audio_treble.

Wallcraft automatically parses custom uniforms in your GLSL code and produces interactive sliders, color pickers, and toggles directly in the Settings UI:

Wallcraft features an intelligent compilation layer. You can use standard GLSL 2.0 fragment shaders with zero manual rewriting:

• void mainImage(out vec4 fragColor, in vec2 fragCoord) is automatically wrapped into standard void main().
• iResolution, iTime, iTimeDelta, iFrame, and iMouse are natively supported.
• iChannel0 through iChannel3 map directly to Wallcraft texture channels.

When your shader references the u_prev_frame uniform, Wallcraft switches into ping-pong Framebuffer Object (FBO) mode. Furthermore, Wallcraft features full multi-pass Shadertoy pipeline execution:

• Buffer Passes: Full native support for Common, Buffer A, Buffer B, Buffer C, Buffer D, and the final Image rendering passes.
• Flexible Channel Routing: Route any buffer's output to another buffer's iChannel0..3 input to create complex fluid dynamics, Navier-Stokes fluid advection, smoke dissipation, reaction-diffusion patterns, or optical feedback loops.
• Built-in Procedural Textures: Bind procedural texture generators directly into channels without external image files: Smooth Value Noise, RG Noise, Rock / Stone Surface, Lichen / Moss Pattern, Wood Grain, Deep Space Stars, and Pebbles Mosaic.

Because Wallcraft runs 24/7 on the user desktop, community widgets must never leak memory or spin CPU cycles while idle:

1. Clean Timers & Listeners: Always clear setInterval, requestAnimationFrame, and window.WallCraft.audio.onStateChange callbacks inside your destroy() method.
2. Pause/resume ownership: When runtime pause is active, timer/rAF callbacks are filtered and tracked audio contexts are suspended. An interval is not removed just because its callback is skipped. Recursive rAF/timeout chains need an explicit restart in resume(). Stop your loops in pause() and clean subscriptions/resources in destroy(); automatic handling is not a zero-CPU or leak-free guarantee.
3. Avoid DOM Thrashing: Do not set textContent or style if values have not changed from the prior frame.