How to embed a diagnostic bookmarklet: Executable, Display, and Hybrid modes
This document explains, in a practical “how-to wiki” style, the three canonical modes for embedding a long JavaScript bookmarklet into an HTML page: Executable Mode, Display Mode, and Hybrid Mode. Each mode is architected so that an engineering team (or an Ivy‑level academic lab) can reason about behavior, safety, and automation potential.
High‑level overview of the three modes
When you embed a large diagnostic bookmarklet into an HTML document, you must decide whether the page should execute the code, only show the code, or preserve the code while keeping the page static. That is exactly what the three modes capture.
1. Executable Mode
The page becomes a live, self‑profiling runtime shell.
- Behavior: The bookmarklet runs automatically via
<script>. - Use when: You want introspection, observers, and JSON streaming to be active by default.
- Risk surface: Any change to the bookmarklet changes page behavior.
2. Display Mode
The code is visible and study‑ready, but never runs.
- Behavior: Code appears as text inside
<pre><code>only. - Use when: Documentation, teaching, or code review is the primary goal.
- Risk surface: Minimal, the page is effectively static.
3. Hybrid Mode
One copy to learn from, one copy to copy.
- Behavior: Code is shown and also stored raw in a non‑executing script tag.
- Use when: You want accurate copy‑paste and high‑quality docs on one page.
- Risk surface: Static by default, still safe for most doc sites.
Executable Mode: building a live diagnostic shell
Executable Mode is for when you want the page itself to behave like a self‑profiling environment. As soon as the document loads, your bookmarklet runs as if a user had invoked it manually.
- Introspection: Scanning DOM, measuring layout, collecting metrics.
- Observers:
PerformanceObserver,MutationObserver, and possibly event listeners for user flows. - Diagnostics UI: Any overlay, sidecar pane, or JSON stream window your code opens.
<body>:
<!-- Executable Mode: runs on page load -->
<script>
/**
* Diagnostic bookmarklet – Executable Mode
* NOTE: Replace the next line with your full bookmarklet body.
*/
(function(){
// <!-- BEGIN BOOKMARKLET PAYLOAD -->
// ... PASTE YOUR LONG BOOKMARKLET CODE HERE ...
// <!-- END BOOKMARKLET PAYLOAD -->
})();
</script>PerformanceObserver and MutationObserver can be chatty, structure the code so
that:
- Observers are debounced: Aggregate changes before logging or streaming.
- JSON stream windows are lazily opened: For example, on a keyboard shortcut:
// Example: only open the diagnostic window on Ctrl+Shift+D
window.addEventListener("keydown", (ev) => {
if (ev.ctrlKey && ev.shiftKey && ev.key.toLowerCase() === "d") {
// open or focus your JSON stream window
}
});Display Mode: building a safe, static documentation page
Display Mode is for training, peer review, and publishing. The code is treated as a primary text artifact, not as an active runtime component.
<pre><code>, you must escape HTML‑sensitive characters:
<becomes<>becomes>&becomes&
<!-- Display Mode: code as text only -->
<pre><code class="language-javascript">
javascript:(function(){
// Your bookmarklet, escaped for HTML:
// <!-- BEGIN BOOKMARKLET PAYLOAD -->
// ...
// <!-- END BOOKMARKLET PAYLOAD -->
})();
</code></pre>- Structure: Top‑level IIFE, configuration, observers, UI overlay.
- Assumptions: Browser APIs, CSP expectations, third‑party dependencies.
- Extension points: Places to plug in other observers or data sinks.
Hybrid Mode: combining readability with raw, tooling‑ready code
Hybrid Mode is often the most “production‑ready documentation” pattern: one copy of the code is optimized for humans, another is optimized for programmatic consumption, and neither executes.
<section aria-label="Bookmarklet (readable version)">
<h3>Readable bookmarklet</h3>
<pre><code class="language-javascript">
javascript:(function(){
// Escaped, formatted version for human readers
})();
</code></pre>
</section><!-- Hybrid Mode: non-executing raw payload -->
<script type="text/plain" id="bookmarklet-raw">
javascript:(function(){
// <!-- BEGIN BOOKMARKLET PAYLOAD (RAW, UNESCAPED) -->
// ... PASTE YOUR EXACT BOOKMARKLET HERE ...
// <!-- END BOOKMARKLET PAYLOAD -->
})();
</script>type="text/plain" as executable JavaScript, but your own tooling (or a small
on‑page helper) can read and export this string verbatim.
<script>
function copyBookmarkletRaw(){
const el = document.getElementById("bookmarklet-raw");
if(!el) return;
const text = el.textContent || el.innerText || "";
navigator.clipboard.writeText(text.trim()).catch(console.error);
}
</script>Executable Mode – methodological notes
Intended use
Executable Mode is appropriate when the page is deliberately positioned as a diagnostic instrument. In an academic or high‑assurance setting, you would typically:
- Describe the runtime behavior in a methods section (what is observed, at what cadence).
- Constrain the environment (browser versions, CSP, required permissions).
- Log configuration so that runs are reproducible and auditable.
Observer wiring pattern
PerformanceObserver + MutationObserver should feed a single, structured event bus rather than ad‑hoc console logs.
A clean pattern is to define a small dispatcher at the top of the bookmarklet, then have each observer publish events into it. That makes later refactoring (e.g., sending data to remote endpoints or saving snapshots) much less invasive.
Display Mode – documentation‑first design
Pedagogical framing
In Display Mode, treat the bookmarklet as if it were a figure or algorithm in a paper. That means:
- Introduce it with a short abstract (“This bookmarklet constructs a self‑profiling shell…”).
- Annotate key sites (observer setup, UI mount, teardown handlers).
- Provide usage examples as narrative steps rather than just code comments.
Static site integration
This mode is ideal for static documentation systems (e.g., GitHub Pages, SSG‑generated sites) because it imposes no runtime risk. Your CI can treat the page as plain content while still exposing the full bookmarklet.
Hybrid Mode – single‑artifact source of truth
Why maintain two representations?
Hybrid Mode acknowledges that humans and tools want different shapes of the same code. The readable block can be formatted, partially elided, or line‑numbered, while the raw block remains byte‑for‑byte identical to the deployed bookmarklet.
Programmatic extraction pipeline
A typical pipeline might:
- Fetch the documentation page.
- Parse the HTML and read
#bookmarklet-raw. - Validate the code (lint, test, size budgets).
- Publish it into a browser extension, a bookmark file, or a CDN asset.
This keeps your “public documentation” and your “runtime distribution” perfectly aligned, which is the standard you want for serious, long‑lived tooling.
Comments
Post a Comment