Stories

Comment by joe-excom

Comment

Comment by joe-excom

Hi HN. I'm Joe, the solo developer behind this project. I left my consulting career 3.5 years ago; I became a farmer/rancher and have been diligently spending my remaining free time on this project.

The Nucleus stack is a few decoupled web technologies that work together as an implementation of the "ASO" architecture (stands for Adapter, State, Orchestrator). Practically, the goal of Nucleus is sophisticated, declarative, simple web apps with low-to-zero JS and no build process.

Architecturally, the "Orchestrator" is the primary innovation here. The original motivation: the web has never had an easy, native way to map data to the document. Every web framework primarily exists to fill this gap; most achieve it by keeping a copy of app state in JS memory and treating the DOM as a compile target. Yet CSS has quietly held templating-like abilities for a long time:

    span::before { content: attr(data-text); }
The "Orchestrator", dubbed "Quark", takes this idea seriously. It's a CSS derivative whose properties mutate the document, rather than style it. It can set attributes, iterate lists, stamp templates, listen for events, dispatch commands, run View Transitions, and more.

"Adapters" are certain elements (native or custom elements) that each bridge the "State" to one external protocol, such as fetch, form, history, WebAuthn, user gestures. They write only their own attributes.

"State" is simply the live DOM.

Two demos to take a look at; both have zero lines of app JS and no build process:

- The Todo demo on Nucleus' landing page is a fully RESTful app in about 30 lines of HTML, 20 lines of Quark.

- The Wrenfield PWA demo is a fictional, full-featured ecommerce site with polished features like SSG, SPA, hydration, web AR/3d models, WebAuthn, View Transitions, touch gestures. Try it on mobile to get a native-like experience. https://wrenfield.excom.dev

The Nucleus site itself is also dogfooding the stack. Opening up your inspector will show a highly declarative document, which is the live State of the app. Other examples are in the sidebar. The Nucleus stack is currently being used in production by a few companies. Open source versions of their apps are coming soon, as demos.

The stack differs from things you're probably aware of:

- HTMX - server owns logic and swaps fragments. Quark owns orchestration on the client, with the document as the only state.

- Lit and other web component frameworks - Custom elements are also part of this stack, and there can potentially be interop. But the ASO architecture advises elements to never render their own opinionated children or business logic. That is left to you.

- Datastar / Alpine - JS expressions or signals inside attrs. Quark lives in a separate, decoupled sheet and has no expressions with side effects. It does not call anything except your named pure functions.

- Blackboard pattern - architecturally, this is the closest relative. The site has an "Advanced -> Prior Art" page which discusses this.

The Nucleus stack is in beta. Here are the edges:

- Quark: unlike CSS, rules will not revert when they stop matching. You need to write the inverse, if needed. This is by design. Regardless, I'm currently exploring the architectural feasibility of rule reversion.

- Quark: certain pseudoclasses like :focus, :checked, :invalid are not observed.

- Quark and the elements rely on some fairly new browser APIs (like the Command API, Baseline 2025). Polyfills will be included in the first stable release.

- Will not play with React and certain other frameworks that lock the DOM to their own internal state. You will need a Shadow DOM as a boundary between them and the Nucleus stack.

Depending on the bundle/loading strategy you choose, the whole stack is somewhere between 1kb and a maximum of 70kb (brotli). This includes all out-of-the-box elements that provide generic functionalities like data fetching, lazy loading, and UI things like drawers, tabs, etc.

I am very keen on hearing feedback on this project. Particularly on the ASO architecture and the Quark language.

Nucleus will remain in beta for a few more weeks, as features are optimized and feedback is incorporated.

Docs: https://nucleus.excom.dev

Repo: https://github.com/excom-dev/nucleus

Architecture: https://nucleus.excom.dev/docs/adapter_state_orchestrator

Replies joe-excom · 9h
Open on HN
Loading the discussion…

Domain filters

Stories from these domains are hidden from every list. Subdomains match too: blocking substack.com also hides danluu.substack.com.

    New collection

    Delete this collection?

    About YAVCHN

    YAVCHN is a reader for Hacker News and Lobsters, with articles and discussions in separate windows or Classic pages.

    Created by Paul Parks and built with PUDL.

    YAVCHN source code on GitHub

    Privacy policy · Terms of use

    Help

    Keyboard

    j / k
    Move down and up the story list. The arrow keys scroll whatever has focus.
    Enter
    Read the marked story in the article reader.
    ]
    Read the next story in the same article-reader applet. Back returns to the previous story.
    p
    Pin or unpin the marked story, which keeps it in Pinned.
    n / N
    Move to the next or previous top-level comment in the window in front.
    c
    Collapse or expand that comment.
    f
    Hide or show the story list.
    Esc
    Close a menu or this help.
    Access key m
    Go to the menu bar. Most browsers take it with Alt on Windows and Linux, and Safari with Control and Option.
    ?
    Show this help.

    Windows

    Each story opens in a window holding its article above its discussion; drag the bar between them to share the room differently. A window can be moved by its title bar, resized from any edge, snapped to a half or a corner by dragging it there, maximised, or minimised to the bar at the foot of the page. Use Window > New reader window to open an empty reader, or Story > Open in new reader window to open another reader for the current article. Docked readers keep their articles when you select another story from the sidebar. Minimized readers can be restored and reused for their site. A window's Next story link reads on down the list in the same window.

    A link in a comment or an article to another Hacker News or Lobsters thread opens that thread in a window too. A link to a single HN comment opens the comment above its replies.

    While a story's window is in front, the Story and Discussion menus in the menu bar hold its commands: pinning, Next story, sorting, collapsing every thread, jumping to the first new comment. Each window also remembers where you were in its article and discussion, so a reload, or Back to a story that Next took you past, finds your place again. Closing a window forgets it.

    The whole arrangement lives in the address, so a bookmark or a shared link brings it back, and Back undoes the last change. Moving between Hacker News, Lobsters, their lists, Pinned and Find changes only the list, and leaves the windows open.

    The list

    The pin at the start of a row keeps the story in Pinned, and the cross at its end hides it. Pinned can be narrowed by words in the title, site or author, by source, and to the stories you haven't opened yet, and ordered by when you pinned them, by points or by comments; the filters are part of the address, so a filtered view can be bookmarked. Scroll past the end of the list to load more. Domain filters, in the View menu, hide every story from a site.

    Collections are named lists of stories. Story > Add to collection files the story in front into one or more of them, and the Collections feed shows them all or one at a time; the menu that chooses collections also creates, renames, and deletes them. A note is your own text on a story. Choose Add note in a story's toolbar to write one; it saves as you type. Rows with a note carry the note mark, and the Notes feed lists every noted story and searches the text of your notes.

    Browsing view

    View > Windowed and View > Classic select the browsing view and save your default in this browser. Window view reuses a reader for each feed. Classic view opens stories and applets as pages. Open as a page is a one-off action that does not change your saved default. Use the Windowed selector to return an article to a window. Direct page links always open as pages.

    Applets

    The Applets menu in the menu bar holds three tools, each a window of its own. Replies to me takes your Hacker News user name and lists the replies to your last thirty comments and stories, checking again every three minutes while it is open, and marking what is new since you last marked them read. Look up a user opens a profile on Hacker News or Lobsters, with their submissions and recent comments, as a commenter's name in any discussion does; the bar at the top of a profile looks up someone else in the same window, and Back returns to the one before. Who is hiring? filters the posts of HN's monthly hiring threads by the words you type.

    They read only what the sites publish to everyone, so none of them asks for a login, and your user name stays in this browser anonymously and is included in retained applet state when signed in.

    Find

    Find takes any link and lists every time it was submitted to Hacker News and Lobsters, so you can read each discussion of it.

    About

    YAVCHN never sees your Hacker News or Lobsters login. The discussion is fetched from each site's public API; to vote or reply, follow the link above the discussion, or the arrow beside a comment, to the source's own site. Without a YAVCHN account, your data stays in this browser. When signed in, pins, collections, notes, blocked domains, and retained reading state are stored with your account and synchronized across devices. Hidden stories and layout stay in this browser. The privacy policy has the details.

    Open source: github.com/paulmooreparks/yavchn. Built with PUDL.