The LLM experience of boreDOM

2026-02-17T00:00:00+00:00

TL;DR

I talk about the changes made to bring LLM Experience design</a> to boreDOM</code>, my testbed zero-build JS runtime that collapses HTML, CSS, JS and state into a single HTML file so models can locate the source of an effect in place. </blockquote>

What does a codebase look like if its primary author is a machine?</h2> If a codebase is mostly written by a machine, do our usual frontend instincts still hold? What do we need to change to make that workflow reliable? And how much can we min-max an LLM’s strengths if we stop designing exclusively for human cognition?I walked this path, looking for answers, adapting and changing boreDOM</code></a> a minimal JS framework (with no bundler or package manager) I keep evolving as I learn where LLM workflows actually break. With little JS boreDOM</code> tries to make components reusable and allow them to be layed out in triplets: <style data-component="my-thing">  </style> <template data-component="my-thing">  </template> <script type="text/boredom" data-component="my-thing">  </script></code></pre> HTML is HTML, style is CSS, and code is JS. These units of triplets can then be placed in a single file index.html or in multiple files through some existing bundler (I use vite when I am hand-rolling them). Working with LLMs pushed me to over-emphasize a single source of truth. The goal started moving slowly from "syntactic clarity for humans" and more into "operational clarity" by making it cheap to discover where an effect originates, and safe to change it coherently. The rest of this post is about that shift from human-readable structure to machine-editable traceability in boreDOM</code>. boreDOM</h3> For boredom the previous LX (LLM-Experience) guides</a> translated into the following design principles: Single place of truth: UI structure + style + behavior live together.</li> Instrumented runtime, everything is machine parseable.</li> Constrained surface area, fewer ways to do the same thing and a limited number of composable things.</li> No build-time indirection, what the model edits is what the browser runs.</li> The whole framework is included in the single file of the app, as if the LLM made it, unmaintainable for humans, but a bit better for deep agentic loops, so long we don't hit their other problems (lost in the middle, etc...).</li> </ol> From here on I'll describe the specific ergonomics I added to boreDOM to make that LX workflow real. Ergonomics for LLMs</h2> To enforce these principles, boreDOM</code> relies on specific mechanics designed for autonomous agentic loops. This is a more technical part, but maybe it can also be applied while vibecoding too. A. Let LLMs self-correct without humans in the loop</h3> I want to give the LLM parseable and deterministic feedback so that it can self-heal in a loop. CLI Validator boreDOM</code> includes a custom CLI linter validator. Actually I don't see it as a linter and more like a context injection engine made specifically to signal the LLM the best practices and idiomatic approaches it needs. It guardrails the semantic boreDOM approaches as well as tries to prevent introducing things that could impair reusability of components and offline usage (introducing Google Fonts, hallucinating directive names, going around components logic and update loop with innerHTML</code> and others, etc...). The CLI tool validator outputs structured actionable errors that forms a lint-fix loop (validate -> fix -> validate again). It can produce warnings for boreDOM</code> specific things, such as when LLMs should be using data-dispatch</code> but instead go and write data-action</code>. Or errors for generic things like when a setInterval</code>/addEventListener</code> is used but not cleaned up. Every warning/error includes a suggestion string, a plain English fix instruction, and sometimes an example of corrected code. The validator tries to re-prompt LLMs with suggestions in its output: > W001: Found data-action="submit" (boreDOM uses data-dispatch) (line 42:7) Suggestion: Rename to data-dispatch="..." (click) or data-dispatch-<event> for other events. Example: data-dispatch="submit"`</code></pre> Having a custom made linter validator improved at lot the success rate of single prompts with boreDOM. Dynamic Import Debug via #sourceURL When boreDOM</code> encounters a <script data-component="some-component"></code> it will extract the script text from it and dynamically import it with import(url)</code>. The url</code> is a temporary URL object from a Blob that has //# sourceURL=...</code> appended to it. The object URL is revoked immediately after the import resolves. The #sourceURL</code></a> allows LLMs to pin point lines for each component script. It produces relative line numbers and points the dev tools to a fictitious URL boredom://default/some-component.js</code>, which is something that LLMs can easily disambiguate. Each component's script is a lazily-evaluated ES module that only gets imported once and can produce a parseable correction signal when an LLM generates a boreDOM component that breaks. This way when the model breaks a component, the console points to boredom://...:linenumber</code>, so it can patch the right script block without guessing offsets. Structured Logs for regex Every console.error</code> and console.warn</code> in boreDOM</code> follows the exact same shape: console.error("[BOREDOM:ERROR]", JSON.stringify({ component: "component-name", message: err.message, stack: err.stack, code: "SCRIPT_LOAD_FAILED", loc: "boredom://default/some-component.js:12", context: { source: "script_load" } // or "state_parse", "_update", etc... }));</code></pre> The idea here is that errors come out in a structured JSON that an LLM can regex out of a log dump. An LLM reading console output can grep for "[BOREDOM:ERROR]"</code>, parse the JSON, and immediately know which component, what failed, and where in the lifecycle. B. Make the default behavior match LLM expectations</h3> Making the runtime transient and fluid towards what LLMs are trying to output is a good way to avoid fighting the weights or going against their training and instead try to leverage their thinking skills. I ended up gifting boreDOM</code> with the following things. Declarative bindings LLMs trained on React/Vue/Svelte default to thinking of bindings as two-way. When they see data-value="local.name"</code> on an <input></code>, they assume typing in the input automatically updates local.name</code>, unfortunately that's not how it works in vanilla DOM, data-value</code> is just an attribute the runtime reads to push state down and without an explicit event listener typing in the <inpute></code> does nothing to state. In boreDOM</code> these values are compiled with new Function</code>s, in a set of constraints that make it safe-ish for the boreDOM</code> strict conditions that it uses it. This way it allow LLMs to write: <input data-value="local.name" /> </code></pre> And it just works, state flows down. Pre-registered event delegation Instead of requiring per-element addEventListener calls, boreDOM</code> pre-registers all 16 supported events (yep, only 16 events are supported) on each component host on setup. Most UI apps use ~16 events, explicitly naming them and limiting prevents hallucinated event types and lifecycle leaks. These can be extended in CONSTANTS.Events if needed. CONSTANTS.Events.forEach((event) => { this.addEventListener(event, (e) => dispatchComponentEvent(this, e, actionType), { capture: useCapture } ); });</code></pre> The LLM just writes data-dispatch="doThing"</code> in the HTML and on("doThing", ...)</code> in the script. No need to keep track of what addEventListeners</code> need to be cleared. Automatic re-rendering via proxies Both state (global) and local (component) are wrapped in a Proxy</code>: const proxy = new Proxy(target, { set(obj, prop, value) { if (Object.is(oldValue, value)) return true; obj[prop] = value; scheduleUpdate(); return true; }, get(obj, prop) { // Deep wraps, so state.projects[0].name = "x" triggers a re-render too: return createReactiveState(obj[prop], callback, cache); }, });</code></pre> LLMs just write local.count += 1</code> and the UI updates. There is a WeakMap</code> cache to prevent infinite proxy wrapping. boreDOM deliberately uses deep proxies and constrained event delegation to reduce syntactic friction for LLMs. I want re-renders to happen automatically, remove them from being explicit in the syntax and into runtime behavior. Again this is the shift from designing for operation instead of for syntax. Think of it as removing hooks from React and instead focusing on the way a LLM will be writing the intentions. This does introduce risks such as recursive mutations that can trigger render loops, or unsupported DOM events that won't fire. These are intentional constraints designed to reduce surface area for generation and prevent common lifecycle errors, at the cost of flexibility. With LLMs I tend to see syntax as a solved problem, so my natural approach is to shift explicitness from boilerplate in authored code to consistency behaviours in runtime that LLMs can inspect and produce at will. C. Flatten the abstractions</h3> Flat destructurable API The component init function receives everything in one flat object: const createInitContext = (component) => ({ on: (name, fn) => registerAction(...), onMount: (fn) => registerHook(...), onUpdate: (fn) => registerHook(...), onCleanup: (fn) => registerHook(...), self: component, ...createComponentContext(component), // { state, local, refs } });</code></pre> This way LLMs can destructure exactly what they need: ({ state, local, on, onMount }) => { ... }</code> without having to keep extra context about class inheritances or import paths. The entire API surface is flat 7 names: on, onMount, onUpdate, onCleanup, state, local and refs (and the ref for the component itself). Components triplets in a single place As I've shown at the start, the architectural format itself is an LLM ergonomy thing, where HTML, CSS and JS are defined per component in the same place with the same tags. In the end everything lives in one file, but this is just an optional final flattening (things can be in split files if it gets too big). LLMs love this when there are semantic anchors across the domain concepts. In boredom this is achieve with the data-component</code> in style, template, and script tags. The tradeoffs</h2> My idea is to optimize for a single author + LLM collaborator model. I mean a very specific single author: me. All of this seems terrible for human teams of many engineers trying to tackle complex products. Systems become unmaintainable without modular boundaries and clear APIs. With boreDOM</code> you lose strict cross-file type checking, fault isolation, refactoring safety, dependency management, and all of the bundler advantages (tree shaking, code splitting, asset hashing, preloading, etc...). This isn't an attempt to replace React, Vue, Svelte, or even trying to overhaul existing frontend architectures. Conclusion</h2> I tried exploring a different category, runtimes designed for environments where code is frequently written, read and refactored by LLMs. In these contexts, I am flipping common knowledge by betting that immediacy, traceability, and low causal distance matter more for AI-driven iteration than strict modular boundaries and build optimizations . boreDOM</code> isn't meant to be a maintainable codebase for big engineering teams. It's an architecture for high-velocity, AI-assisted prototyping and it treats code as "disposable" or "constantly mutable" rather than a permanent monument. Current LLMs are still 'DX-native', they are trained on the very spaghetti of indirection I'm trying to solve. This inconsistency isn't a failure of the rearchitecture I am proponing but more like a symptom of the existing training gap. Maybe in the future they will have that capability of determinism and provide for greater experiments. For now, this is exploratory work. The architectural patterns are strong enough to justify continued experimentation. I believe that in the future we will be spending more time designing the environment where the code writes itself, as a sort of protocol of intuition between us and our partner that has a 256k context window and zero intuition. If you want to experiment with this architecture yourself, or just want to see how an LLM handles a zero-build framework, you can check out the boreDOM landing page</a>. npx @mr_hugo/boredom init</code> Feed it to Claude or Cursor, and let me know if it fails awesomely or brilliantly.

R.I.P. Rest In Prompt

2026-02-16T00:00:00+00:00

TL;DR

LLMs tend to mislocalize when there are multiple sources of truth, so they can fail even while generating "correct" code. This post explores what frontend architecture looks like when the primary collaborator is an LLM. I call this LLM Experience (LX): optimizing for discoverability, traceability, and machine-readable runtime feedback over human-centric modularity. </blockquote>

"Make the button more blue"</h3>
Think about it, changing a button color in a modern framework such as React, can be a task that spans component code, provider tree traversals, theme tokens, CSS vars, and build-time layers.
This is mostly a lookup problem and not so much a "thinking" problem because in this scenario to change a color we would have to trace through the following:

Where is the value defined?</li>
What layer owns it?</li>
What overrides it?</li>
What runtime state mutates it?</li>
What token maps to it?</li> </ol>
We humans solve this lookup problem using the Dev tools inspector, jumping definitions and class names, toggling states and modifying live styles with a bit of intuition and experience.
For an LLM it's also a lookup problem, but with the failure caveat that it can pick the wrong thing and still produce a plausible looking patch.
Humans debug this by inspecting computed styles and jumping definitions. LLMs don't have that interactive loop, so they often edit Button.tsx, see no effect, then "fix it" by adding inline styles or duplicate tokens... and now the codebase has two competing truths.
An LLM will give us a fast answer and make it look effortless by confidently editing Button.tsx</code>. But its retrieval might have caught the wrong files, maybe the real color is coming from the theme provider, and produce a slightly off result because even a 1M-token model will fail if you include the wrong stuff.
Things made for humans that humans struggle with are amplified now. Stuff we consider midly annoying can be a reliability killer for models.
Where prompts go to die</h2> I keep on inventing small things, functions, frameworks, tools, widgets. Things for fun. There is a massive blocker nowadays in all of these, that is if you try to invent a new language, or library, or framework, then LLMs will have to look at it from their existing training. You need to be prepared for LLMs to make moves that only make sense inside ecosystems they've seen billions of times. If its a new JS frontend framework, then LLMs would do things like randomly inject tailwind classes, setup a bundler and package manager, or assume the occasional React pattern of useEffect</code> where dependencies are laied in an array and cleanup function is the one being returned. This is a hard situation we are now at. Anything slightly offset from the mainstream will be fighting the weights of LLMs. My attempts at prompt-engineering around these didn't help and only made it clear that the problem would need another angle besides prompts. I then shifted towards re-architecturing things for discoverability. Our clean code is a context tax</h3> These machines are only deterministic in a very broad and abstract statistical way. If the codebase doesn't make it easy to locate the source of behavior, I find that models will confidently edit the wrong place or rewrite parts of the system into something they recognize. I was forcing these machines to use my new tool the way they use mainstream stacks (Webpack, file splitting, npm, Tailwind, Redux, etc.). But my tool still lived inside the same broad architectural assumptions, only without the cultural momentum those ecosystems have. So I stopped trying to out-prompt the model, and started reshaping the architecture around how LLMs actually approach code. Developer Experience (DX) vs LLM Experience (LX)</h2> My way into the LLM-experience experience was to avoid the common tactic of making use of the context window to artificially cram awareness into it through prompts. There is some psychology game here. What is implicit for humans in a codebase, but needs to be explicit for machines? DX</h3> Developer Experience (DX) is the set of design choices we've converged on to help human teams build and maintain software over time. It assumes humans have limited short-term memory and need strong boundaries to keep complexity tame. It assumes syntax is hard to manage, that code layout and configuration needs to be extremely versatile and layered through to cater for many possible scenarios so that it does not become too "opinionated" or too strict (which can be good things too). We humans like to have our logic split in small sections, divide and conquer, remove the noise around, avoid goto, premature-optimization is the root of all evil, do one thing and do it well, and uni-uni-uni-uni-unix problems to infinity. Be it files, components, objects, functions, blocks of { code }, if's for's, relationships, life choices, whatever. LX</h3> LLM Experience (LX) is a different target, it comprises the set of choices that make a codebase easier for an LLM to read, locate the cause of an effect, modify safely, and validate via feedback. It assumes that syntax is super easy and that the hard part is finding the correct source of truth and changing it without breaking invariants. Humans navigate complexity using amazing implicit knowledge and spatial awareness, we go through folders, naming conventions, import strategies, design patterns, source-to-source compilation, like it was easy and benefitial. LLMs however are more into navigating complexity using contiguous text and local coherence. We both can do both things, but some are better at some. "I have updated index.ts, index.ts and index.ts. If you want I can also patch index.ts and index.ts next." Their sense of place has been improving and will hopefully make a lot of this obsolete soon. LX in one sentence: reduce ambiguity about where truth lives, and make runtime feedback point back to the exact edit location. Design for LX</h2> There is an apparent tension between DX and LX, where DX adds indirection to make systems scalable the LX removes indirection to make edits reliable. In the end of the day both LX and DX are trying to reach the same outcome and goal. Both are trying managing the reliability of changes, just through different layers of abstraction. Feature</th> Developer Experience (DX)</th> LLM Experience (LX)</th> </tr> </thead> Primary Goal</td> Minimize cognitive load for humans.</td> Maximize context density/traceability for AI.</td> </tr> Structure</td> Modular, split files, deep hierarchies.</td> Co-located sources of truth, shallow hops (often single-file artifacts).</td> </tr> Logic</td> Abstractions (Hooks, Providers, HOCs).</td> Explicit, linear, and "in-place" logic.</td> </tr> Feedback</td> Human-readable error messages.</td> Machine-parseable JSON logs/signals.</td> </tr> </tbody> </table> In LLM Experience, you collide and reduce the sources of truth, so that it is easier to find the places a behavior could be hiding. This means bringing structure, style, state, and behavior close together, to try to reduce the casual distance of moving parts, while producing fewer valid ways to do the same thing, to try to constraint the surface area. Errors and traces are structured to try to instrument runtime feedback for machines. Essentially LX is an attempt to make it hard to edit the wrong thing in the wrong way, by architecturing to provide a predictable runtime behavior and deterministic logs and feedback above code semiotics. It's a shift from syntactic explicitness to operational explicitness. You might already be LXing</h3> Take a look at your current source code, and try to answer these: Can I locate any UI effect in <= 2 hops?</li> Is there a single authoritative source for tokens?</li> Do runtime logs point to an exact edit location?</li> Can an LLM run validate -> fix without guessing line offsets?</li> If an agent deletes this component and regenerates it from scratch, will it break the rest of the app?</li> Can this logic be validated without a complex mocking setup?</li> Can I find every occurrence of a feature using a single regex, or is the logic smeared across layers?</li> </ul> Anyway you get the idea, LX is about information density, trying to provide the highest ratio of reasoning per token possible, so that the model doesn't drift away easily. LX patterns you can use</h2> One authoritative place for tokens/theme/state mutations</li> Shallow hops: an on-screen effect should be reachable in ≤2 jumps</li> Stable identifiers that show up in markup and logs</li> Machine-parseable errors (JSON envelopes with code, component, loc)</li> Constrained surface area: fewer sanctioned ways to wire events/state</li> A validator loop (validate -> fix -> validate) that doesn't require human intuition</li> </ul> Conclusion</h2> LLMs strive with less ambiguity. When a UI effect has many plausible owners, models can confidently patch the wrong one and then compensate by duplicating logic. LX is my attempt to design against that failure mode by collapsing sources of truth, reduce indirection, and make runtime feedback machine-readable and location-specific. In the next post</a> I'll show the concrete mechanics I used to make this real in my testbed JS framework boreDOM</code></a>. Where I introduced a CLI validator that drives validate->fix loops, #sourceURL</code> mapping so console errors point to the exact block to edit, structured JSON logs, and a constrained event/state surface that reduces generation drift. I was banned from Claude for scaffolding a CLAUDE.md file 2026-01-22T00:00:00+00:00 API Error: 400 { "error": { "type": "invalid_request_error", "message":"This organization has been disabled." }, ... }</code></pre> One minute I'm a €220/month "Max 20x" AI "power user" (is this even a thing?). The next, I am a disabled non-person "organization". Like a lot of my peers I was using claude code CLI regularly and trying to understand how far I could go with it on my personal projects. Going wild, with ideas and approaches to code I can now try and validate at a very fast pace. Run it inside tmux</code> and let it do the work while I went on to do something else. Until in one of these sessions I got presented with that response. Organizations of late capitalism, unite!</h2> My account was banned! no warning and no feedback, just that message saying that my request was invalid because I am a disabled organization. I wasn't even doing anything groundbreaking, in fact, I was asking it to tune a tool I use to do project scaffolding. Yes you read that right: project scaffolding! Probably one of the most boring things you can think of doing! The quine is the quine</h2> So I asked claude to update my scaffolding tool so that it would include a CLAUDE.md file in there with baked instructions for a particular homemade framework (cof boreDOM</a> cof). I was playing like a "human-in-the-loop" middleware for these LLM tools. Like watching one instance of Claude try to "boss around" another instance of itself, and the platform's security guards mistook it for a riot. To help understand this, there are three main characters in this story: Claude A</li> Claude B</li> A disabled organization (me)</li> </ul> The loop was like this: The disabled organization asked Claude A to update the scaffold tool with a cool CLAUDE.md</li> The disabled organization went on and started a new project with the tool, opened a claude in there (Claude B) and asked for a complex task to be done</li> Whenever Claude B made a mistake, the disabled organization would go to Claude A, paste the error, and say something like "hey, Claude B made this error"</li> goto I</li> </ol> The loop repeated until the disabled organization was told it was a disabled organization. Banned! STOP! YOU ARE WRONG</h2> I just wanted a standard context file for new projects. At one point Claude A got somewhat annoyed with Claude B, and started shoutting! writting in en-US instead of en-GB, that is: ALL CAPS. I went on to check the file, and it was getting littered with these kind of instructions to make Claude B do something instead of what it would try to do. My guess is that this likely tripped the "Prompt Injection" heuristics that the non-disabled organization has. I would love to see the face of that AI when it saw its own "system prompt" language being echoed back to it. Or I don't know. This is all just a guess from me. "It’s not just bad support; it’s automated exclusion."</h2> So I went running to read their docs. What was going on here? Made an appeal, which was a link to a google docs form, with a textbox where I tried to convince some Claude C in the multi-trillion-quadrillion dollar non-disabled organization that I was not only a human but also a well-intended one. I got no reply. Not even an automatic response. 0 comms. So I wrote to their support, this time I wrote the text with the help of an LLM from another non-disabled organization. I got no reply. Not even an automatic response. And to wonder that people complain about civil servants, eh, wait until you have to deal with one of these expensive machines! After a couple of days I got an e-mail: Credit note from Anthropic, PBC for invoice #...</h3> Yes, the only e-mail I got was a credit note giving my money back. It's like they're saying "We don't want to talk to you anymore, here is some hush money". But hey guys, it is not a conversation if it is one-way only, and here I am talking to a wall. I didn't even get to have a "It's not you, it's us." I just got a credit note. Ahaha I'm so happy!</h2> I'm glad this happened with this particular non-disabled-organization. Because if this by chance had happened with the other non-disabled-organization that also provides such tools... then I would be out of e-mail, photos, documents, and phone OS. AI moderation is currently a "black box" that prioritizes safety over accuracy to an extreme degree. If you are automating prompts that look like system instructions (i.e. scaffolding context files), you are walking on a minefield. Conclusion</h2> I got my €220 back (ouch that's a lot of money for this kind of service, thanks capitalism). I have reframed the whole scaffolding project, and reverted all the code Claude did there. Soon I will re-release boreDOM</a> with a new angle and approach, without the help of Claude. I am trying to turn it into a JS framework for LLMs (llm first, or even llm only, it now has no API). To produce and iterate on those single.html files that these tools are now bringing to the world. If you want to take a look at the CLAUDE.md that Claude A was making Claude B run with, I commited it and it is available here</a>. Again to wrap this up: this whole post is just my hypothesis. Claude was not doing anything other than iterating on this file at the moment I got the ban. And I haven't heard from them about this anymore (or ever). "you got to understand that these organizations have a lot of users..." PNGine: a WebGPU shader portability engine 2025-12-31T00:00:00+00:00 I've been working on a minimal shader portability engine since mid-2024. It was used by me and my friend icid to create a demo for the Inércia demoparty 2025 that happened in Almada in early December. The demo failed spectacularly. We couldn't show it during the competition because it crashed the browser tab on the machine running the demos. Shortly after, we found it also didn't work on most computers and devices. At one point it even stopped working on my own machine. After the party we spent a few days thinking over what went wrong. That led me to fix and redesign parts of the engine, optimize loose ends I'd left for "future me or some capable LLM," and finally write this post before the story repeats itself. </video> What PNGine Is</h2> Bundle WebGPU shaders and pipeline configuration into a single portable file. Run it anywhere with a small viewer. That's it. One file containing your render passes, compute shaders, buffers, textures, bind groups, etc. Hand it to a viewer on any platform with WebGPU support, and it can be played. The file can be a PNG. The PNG format allows custom binary chunks after the image data, working roughly like a .zip that holds things in it but in this case it shows a picture by default (the png image). Embed your WebGPU bundle in the PNG, and suddenly images can move if you have a viewer that can look for the WebGPU bundle in them. It feels a bit like magic. But PNGine also works with plain .zip files if you prefer. The PNG thing is just the flashy option. What This Is Not</h2> Not an animation format. For that, use Rive or Lottie. Not a new vector format. For that, use SVG or something like that. Not a design tool. For that, use Figma or Sketch. Not a rendering engine. You write the shaders. PNGine just packages and runs them. Maybe it should have been called DIYengine. Not a way to make any PNG move. The image is just a container. Most of my files are actually .zip. How Small?</h2> Self-contained PNGs with embedded WebGPU information and executor: A triangle: ~13 KB (500 bytes bytecode + tailored executor). A rotating 3D cube with depth buffer: ~14 KB. A full boids flocking simulation with compute shaders: ~20 KB. Embedding the WebGPU information and its executor in the .png guarantees that they are self contained. No need to be fighting mismatching players/viewers versions bugs that can only play certain payloads in certain ways. A PNG holds everything that it needs to be played as it was intended when it got bundled by the creator of the visuals being shown. Everything except the tiny extractor you need to have to read these extra chunks. How?</h2> From a design perspective, the WebGPU instructions got moved into a full declarative space. Things are described in a Domain Specific Language that follows the spec but declares the whole WebGPU non-iteratively, abstract enough so that it can be decomposed into a payload that can be run in the browser or in your favorite native WebGPU implementation ( dawn</a>, wgpu</a>, any compatible web browser, etc...). The DSL compiles to a custom bytecode, which DEFLATE-compresses into the PNG. The compiler builds a tailored WASM executor containing only the parts your shader needs to run—typically 12-18 KB. Together they're small enough to inline in HTML or use as a favicon. The DSL</h2> The user facing part of PNGine uses a domain-specific language that maps directly to WebGPU. The rule is simple: every device.create*()</code> function becomes a #macro</code>: device.createBuffer(...) → #buffer name { ... } device.createTexture(...) → #texture name { ... } device.createRenderPipeline(...) → #renderPipeline name { ... }</code></pre> The "create" disappears, "#" takes its place, and you give it a name to reference elsewhere. What goes inside { }</code> are the function arguments, written as name=value</code>. The names come directly from the WebGPU spec—I didn't invent them. Here's a minimal triangle: #shaderModule code { code=" @vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f { var pos = array<vec2f, 3>( vec2f(0.0, 0.5), vec2f(-0.5, -0.5), vec2f(0.5, -0.5) ); return vec4f(pos[i], 0.0, 1.0); } @fragment fn fs() -> @location(0) vec4f { return vec4f(1.0, 0.5, 0.0, 1.0); } " } #renderPipeline pipeline { layout=auto vertex={ module=code entryPoint=vs } fragment={ module=code entryPoint=fs targets=[{ format=preferredCanvasFormat }] } } #renderPass pass { colorAttachments=[{ view=contextCurrentTexture clearValue=[0 0 0 1] loadOp=clear storeOp=store }] pipeline=pipeline draw=3 } #frame main { perform=[pass] }</code></pre> Compile it: pngine triangle.pngine -o triangle.png</code> That's your ~500 byte triangle, embedded in a PNG alongside a WASM executor ready to show it. Shape Generators</h2> Writing vertex data by hand is tedious. So the compiler can generate it: #data cubeVertices { cube={ format=[position4 color4 uv2] } // ^ a cube! } #buffer vertexBuffer { size=cubeVertices usage=[VERTEX] mappedAtCreation=cubeVertices // ^ names can be used as references to WebGPU parameters // The compiler understands and takes care of everything beforehand }</code></pre> This generates a unit cube with 36 vertices at compile time. The format=</code> specifies what attributes each vertex has: position, color, normals, UVs. No more copying vertex arrays from tutorials. Available shapes: cube</code>, plane</code>. More coming. Built-in Uniforms</h2> For animation, you need time and canvas dimensions. Instead of wiring that up yourself: #buffer uniforms { size=16 usage=[UNIFORM COPY_DST] } #queue writeTime { writeBuffer={ buffer=uniforms bufferOffset=0 data=pngineInputs } } #frame main { perform=[writeTime renderPass] }</code></pre> The pngineInputs</code> identifier gives you 16 bytes every frame: time (f32), width (f32), height (f32), aspect ratio (f32). Your shader just reads them. This is the only builtin identifier of the engine. All custom uniforms can be set using your data as initialization and are available in the viewer API to be written to. </video> The Architecture</h2> ┌─────────────────┐ │ DSL Source │ Human-readable .pngine file └────────┬────────┘ │ compile ▼ ┌─────────────────┐ │ PNGB Bytecode │ ~500 bytes to ~8 KB └────────┬────────┘ │ embed ▼ ┌─────────────────┐ │ PNG File │ Image + bytecode + tailored executor └────────┬────────┘ │ load ▼ ┌─────────────────┐ │ WASM Executor │ ~15 KB, interprets bytecode └────────┬────────┘ │ calls ▼ ┌─────────────────┐ │ WebGPU │ Your GPU does the work └─────────────────┘</code></pre> The compiler does the heavy lifting. It parses the DSL, resolves references, validates everything, and emits compact bytecode. The executor is deliberately simple—it just reads opcodes and calls WebGPU functions. No surprises. WGSL shader strings</h2> The shader strings are compressed in the PNG. They are validated and minified through miniray</a>. Miniray also provides special reflection data on them which allows variables to be mapped before and after minification, and accessed in a natural way through the viewer API, with all the memory layouts and offsets already baked in. The Interpreter Trade-off</h2> The WASM interpreter is bundled inside the PNG by default. The compiler analyzes your DSL and builds a tailored executor containing only the parts you need (render, compute, animation, etc.). This keeps each file self-contained—no external WASM file to host or fetch and no complex viewer. This has consequences: The bad: If you have multiple PNGine canvases on one page, each loads its own interpreter. The size accumulates, sure it's small, slowly but steadily. The ugly: If I fix a bug in the interpreter, you need to recompile your PNGine files. I can't just push a fix and have everyone benefit. The good: If it works, it works. Future updates won't break it. You test it where it needs to run, and that exact version ships with your file. This trade-off made the interpreter a critical piece. It has to be tiny, fast, and unsurprising. All complexity lives in the compiler, who does the heavy lifting. The Viewer</h2> A small amount of JavaScript loads and runs PNGine files executors with their payloads: import { destroy, draw, play, pngine } from "pngine"; // Load from PNG into a canvas const p = await pngine("shader.png", { canvas: document.getElementById("canvas"), }); // Option 1: Let it animate play(p); // Option 2: Control it yourself draw(p, { time: audioContext.currentTime }); draw(p, { time: videoElement.currentTime }); draw(p, { time: slider.value }); // Cleanup when done destroy(p);</code></pre> At its core, PNGine is stateless: draw(p, { time })</code> renders one frame at a specific time. You control when frames render. But because "give me an animation loop" is so common, convenience functions exist: play(p)</code>, pause(p)</code>, stop(p)</code>, seek(p, time)</code>. Use them or don't. Hook it to WebAudio, a scroll position, a MIDI clock, or plain requestAnimationFrame. Your call. Try It Yourself</h2> This PNG contains a WebGPU shader. It looks static, but inside there's bytecode waiting to run. Download pngine_logo.png</a> </div>

`Try It Yourself</h2>This PNG contains a WebGPU shader. It looks static, but inside there's bytecode waiting to run.</p> Download pngine_logo.png</a> </div>`

The LLM experience of boreDOM

Ergonomics for LLMs</h2>
To enforce these principles, `boreDOM</code> relies on specific mechanics designed for autonomous agentic loops. This is a more technical part, but maybe it can also be applied while vibecoding too.</p>`
`</p>`

R.I.P. Rest In Prompt

I was banned from Claude for scaffolding a CLAUDE.md file

PNGine: a WebGPU shader portability engine

The LLM experience of boreDOM

Ergonomics for LLMs</h2> To enforce these principles, boreDOM</code> relies on specific mechanics designed for autonomous agentic loops. This is a more technical part, but maybe it can also be applied while vibecoding too.</p> </p>

R.I.P. Rest In Prompt

I was banned from Claude for scaffolding a CLAUDE.md file

Conclusion</h2> I got my €220 back (ouch that's a lot of money for this kind of service, thanks capitalism). I have reframed the whole scaffolding project, and reverted all the code Claude did there.</p>

PNGine: a WebGPU shader portability engine

Ergonomics for LLMs</h2>
To enforce these principles, `boreDOM</code> relies on specific mechanics designed for autonomous agentic loops. This is a more technical part, but maybe it can also be applied while vibecoding too.</p>`
`</p>`