Skip to content

JavaScript API

Jump to bottom
KabanFriends edited this page Aug 27, 2026 · 2 revisions

Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.

Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.

Mount the advancement viewer

<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>

Mount the item GUI

<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>

items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.

What the container needs

Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.

Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.

Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.

Both functions are async

mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.

On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.

try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}

The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.

Tearing a widget down

Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.

constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();

In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:

useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);

The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.

Cross-origin rules

The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.

Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.

Where the textures come from

The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.

Serve the widget yourself and the same rule applies to your copy:

import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";

That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.

One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:

awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});

Every option

Home

Embedding

Reference

Building bundles

Running it yourself

Clone this wiki locally

, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
JavaScript API · KabanFriends/mcwidgets Wiki · GitHub
Skip to content
JavaScript API
Jump to bottom

KabanFriends edited this page Aug 27, 2026
·
2 revisions
Mount a widget into an element on your own page. Use this when the widget has to sit in your DOM: when your page controls it, when you need several instances, or when an iframe is in the way. If you just want a picture on a page, Embedding with iframe is less work.
Each widget is one self-contained ES module. It has no runtime dependencies, ships no CSS file, and injects the few styles it needs into document.head when it mounts.
Mount the advancement viewer
<divid="tree" style="position: relative; width: 100%; height: 420px;"></div><scripttype="module">import{mountAdvancements}from"https://mcwidgets.kaban.sh/advancements/viewer.js";awaitmountAdvancements(document.getElementById("tree"),{bundleUrl: "https://example.com/mc/advancements/bundle.json",});</script>
Mount the item GUI
<divid="craft" style="position: relative; width: 100%; height: 220px;"></div><scripttype="module">import{mountItemGui}from"https://mcwidgets.kaban.sh/itemgui/itemgui.js";awaitmountItemGui(document.getElementById("craft"),{bundleUrl: "https://mcwidgets.kaban.sh/bundles/itemgui-demo/bundle.json",gui: "crafting_table",items: {crafting1: "diamond",crafting2: "diamond",crafting3: "diamond",crafting5: "stick",crafting8: "stick",result: "diamond_sword",},});</script>
items also accepts the string form used by the items query parameter, so "crafting1=diamond,result=diamond_sword" is equivalent for those two slots.
What the container needs
Give the container an explicit width and height. The widget fills it and picks the largest whole-number GUI scale, 1 to 4, that fits. It never draws at a fractional scale.
Give the container position: relative as well. Errors are drawn as an absolutely positioned panel that replaces the container's children, and without a positioned ancestor that panel escapes to the nearest one.
Resizing is handled for you. The widget observes the container and re-lays out, so a container sized in percentages or with flexbox works.
Both functions are async
mountAdvancements and mountItemGui return a promise that resolves once the bundle is loaded and the first frame is on screen. The resolved value is the widget instance.
On failure they do both things: they draw an error panel into the container, and they reject. Catch the rejection if you want to react in code, but you do not have to render anything yourself.
try{constwidget=awaitmountAdvancements(el,{ bundleUrl });}catch(err){console.error("advancement embed failed",err);}
The panel names the failing URL and lists what to check. Troubleshooting covers what each message means.
Tearing a widget down
Call destroy() on the instance. It removes the widget's DOM and detaches its resize and input listeners. Always call it before you remove the container, or the observers outlive the element.
constwidget=awaitmountItemGui(el,options);// laterwidget.destroy();
In a component framework, mount in the effect that runs after the element exists and destroy in its cleanup:
useEffect(()=>{letwidget;letcancelled=false;mountAdvancements(ref.current,options).then((w)=>{if(cancelled)w.destroy();elsewidget=w;});return()=>{cancelled=true;widget?.destroy();};},[]);
The cancelled flag matters because mounting is asynchronous. A component that unmounts during the fetch would otherwise leave a live widget behind.
Cross-origin rules
The module is served with Access-Control-Allow-Origin: *, so importing it from another origin works.
Your bundle.json is fetched from the page's origin, because that is where the module runs. Same-origin bundles need no headers. A bundle on another host must send Access-Control-Allow-Origin. Icons and textures load as images and need no header either way.
Where the textures come from
The widget resolves its textures and its font relative to its own module URL, so importing from https://mcwidgets.kaban.sh/advancements/viewer.js finds them at https://mcwidgets.kaban.sh/advancements/assets/. Nothing to configure.
Serve the widget yourself and the same rule applies to your copy:
import{mountAdvancements}from"/vendor/mcwidgets/advancements/viewer.js";
That looks for /vendor/mcwidgets/advancements/assets/. Keep the module and its assets/ directory together and it is correct. Self-hosting produces exactly that layout.
One case breaks the rule. If you run the widget through your own bundler, the module ends up inside your build output and its assets do not follow. Set assetBase to wherever you copied them:
awaitmountAdvancements(el,{bundleUrl: "/mc/advancements/bundle.json",assetBase: "/static/mcwidgets/advancements/assets/",});
Every option
Home
Embedding
Reference
Building bundles
Running it yourself
Clone this wiki locally