Reframe front.js as an educational reference implementation - #1
Open
watthem wants to merge 5 commits into
Open
Conversation
…egacy duplication Repositions front.js as a readable, tested reference implementation of browser reactivity + Islands Architecture (portfolio piece) rather than a production framework, and clears the mid-refactor debris that made it read as abandoned. - Add website/docs/guides/how-reactivity-works.md: a guided walkthrough of the ~150-line reactivity engine (val/run/calc, currentRun tracking, error isolation), including an honest write-up of the dependency-cleanup limitation that a production signals library solves and this one omits. - Reframe README with a reference-implementation banner and repoint all stale links (wiki/*, docs/BLUEPRINT.md, examples/, CDN) to their real relocated targets under docs/architecture, docs/strategy, website/. - Fix invalid npm scope @front.js/* -> @frontjs/* (dots are not allowed in npm scope names; the packages could not have published as-is). - Fix watch-mode test hang: package `test` scripts now use `vitest run`, with `test:watch` for the watch workflow. - Remove legacy single-package duplication now superseded by the monorepo: root src/, tests/ (byte-identical to packages/core/tests/), build.config.js, and package.json.old. Point tsconfig include at packages/*/src. - Update CLAUDE.md to describe the actual monorepo layout and repoint its doc references. All 79 tests pass; bundle holds at 1.43 KB gzipped. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
Leans into the reference-implementation positioning: turn the docs into a teaching resource organized around who the site is for, and add a fact-checked "Platform First" guide on the new HTTP QUERY method. - website/docs/guides/README.md: an audience-defined learning path that sequences the existing guides into a curriculum (Orientation → Reactivity → Platform → Integrating → Edges), each step stating prerequisites. - website/docs/guides/query-method.md: teaches the HTTP QUERY method (RFC 10008, Proposed Standard, June 2026) — the read-with-a-body verb — and how a front.js island fetches with it. Includes the real fetch() gotchas (uppercase method token, cross-origin preflight, server support), each checked against the WHATWG Fetch Standard, with sources linked inline. - docs/strategy/AUDIENCE.md: content north-star — primary audiences, what each needs, and the principle that every load-bearing fact is verified against a primary source before publishing. - README: link the guided Learn path from the front door; add an author's note framing the project as a public learning space. - .gitignore: reserve vault/, Vaults/, and *.private.md so the private fact-check knowledge base can never leak into the public repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
…0008) A working, in-page demonstration of the QUERY verb — dogfooded as a front.js island — that runs on a static host with no backend. - website/examples/query-method.html/.js: a search island that fetches with `method: 'QUERY'`, putting the query in the request body. Includes an "On the wire" inspector showing the method sent, the method the server received (proving it arrives verbatim), the HTTP status, and the JSON body. - website/examples/query-sw.js: a Service Worker that intercepts the request, reads the method exactly as it arrived, and answers from a client-side catalog — so it's a real QUERY request observable in DevTools → Network, with no origin server. Rejects non-QUERY verbs with 405 to teach semantics. - Verified end-to-end with Playwright + Chromium: the request goes out as QUERY and the worker observes `request.method === 'QUERY'` (no normalization), on both the initial load and a reactive re-query. - Registered in examples.json (tested: true) and featured on the examples index; the QUERY guide now links the live demo. - Fix a dangling import in the disabled github-user.js example that pointed at the removed root src/ (now uses ../front.esm.js like the other examples). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
…ivity An interactive dependency-graph visualization, dogfooded as a front.js island and rendered reactively with uhtml's svg tag. - website/examples/signal-graph.html/.js: two independent reactive chains (a,b → a+b → ×2 → log₁ and c → c² → log₂) built from real val + run primitives. Each derived node is an actual run, so the highlight you see is genuine re-execution, not an animation. Nudging a value lights up only the branch that depends on it and shows per-node recompute counts, making the core lesson — work is proportional to the dependency graph — visible. - Verified with Playwright + Chromium: changing `a` recomputes only the a/b chain and never the c branch (and vice-versa); 8 nodes render, no console errors. - Registered in examples.json (tested: true), featured on the examples index, and linked from the "How the Reactivity Works" guide as a see-it-first entry. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
Add "How the Reactivity Works" and "The QUERY Method" to the docs app's navigation registry so they appear in the site's Guides sidebar, not just from GitHub and the README. Both follow the same guides/*.md pattern as the existing entries and are fetched relative to /docs/. The Learn-path README landing is intentionally left out of the SPA nav: its body is a list of .md cross-links, which the docs app's link handler doesn't route (a pre-existing quirk). It remains the front door on GitHub, where those links resolve correctly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Repositions front.js from an abandoned-looking prototype into a deliberate educational reference implementation and portfolio piece: a small, tested, readable exploration of how modern front-end frameworks actually work (fine-grained reactivity/signals, Islands Architecture, secure-by-default hydration). The framework code is unchanged — this PR is about positioning, honest docs, cleanup, and two interactive teaching demos.
The work lands in four coherent steps (one commit each):
docs→website/docs/guides/how-reactivity-works.md) that ends with the one limitation a production signals library solves and this one deliberately doesn't. Removed mid-refactor debris: byte-identical duplicate rootsrc/+tests/, stalebuild.config.js,package.json.old. Fixed the invalid npm scope@front.js/*→@frontjs/*(dots aren't legal in npm scopes — it could not have published). Fixed a watch-modetestscript that hung CI (vitest→vitest run).website/docs/guides/README.md) that sequences the guides, plus a content north-star (docs/strategy/AUDIENCE.md) and a fact-checked "Platform First" guide on the new HTTP QUERY method (RFC 10008).method: 'QUERY'(query in the body), answered by a Service Worker so it's a real request on the wire with no backend.val/runprimitives — change a value, watch exactly which derived values and effects recompute (and which don't).Related Issue
N/A — positioning/documentation initiative.
Type of Change
Checklist
Code Quality
Testing
npm testpasses (79 tests across@frontjs/coreand@frontjs/actions)Bundle Size
npm run size-checkpasses — runtime holds at 1.43 KB gzipped (budget 5 KB). No runtime code changed.Documentation
docs/architecture/ENGINE.mdand the new reactivity walkthrough (the template'swiki/API.mdpath predates the docs move)docs/architecture/BLUEPRINT.mdreviewed — no architectural change (framework code untouched)docs/architecture/STANDARDS.md(Headless Reactivity, Platform First)Security
eval()ornew Function()Deployment
file://)Verification (Playwright + Chromium)
Both interactive demos were driven headless and asserted, not eyeballed:
QUERYand the Service Worker observesrequest.method === 'QUERY'verbatim (no normalization), on both initial load and a reactive re-query. HTTP 200, zero console errors.arecomputes only thea + b → × 2 → log₁chain and never thec²branch (and vice-versa), confirming fine-grained isolation. 8 nodes render, zero console errors.Additional Notes
.gitignorereservesvault/,Vaults/,*.private.mdso it can't leak).wiki/API.md,docs/BLUEPRINT.md); those live underdocs/architecture/now, and the checklist above reflects the real locations.🤖 Generated with Claude Code
https://claude.ai/code/session_01CJcGUWDv2fo2sTwKqC5nBG
Generated by Claude Code