@zoijs/core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to Zoijs are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and Zoijs follows
+[Semantic Versioning](https://semver.org/) (see `VERSIONING.md`).
+
+## [1.0.0] — Unreleased
+
+First stable release. The public API is frozen at seven functions.
+
+### Public API
+- `html` — tagged-template renderer (no JSX, no build step).
+- `mount(component, target)` → `unmount()`.
+- `createState(value)` → `{ get, set, peek }`.
+- `computed(fn)` → `{ get, peek }` — lazy, cached, value-gated.
+- `each(items, keyFn, renderFn)` — keyed list reconciliation.
+- `configure({ dev })` — development/production mode.
+- `onCleanup(fn)` — teardown for components and list items.
+
+### Features
+- Fine-grained, direct DOM updates (no Virtual DOM); setup runs once.
+- Push-pull reactive core with automatic dependency tracking and microtask batching.
+- Owner-scoped cleanup; deterministic teardown on unmount and list-item removal.
+- Context-aware template parser (quoted/unquoted/partial/multi-hole attributes,
+  boolean/URL/aria/data attributes, SVG, nested templates and lists).
+- Secure by default: inert text, URL-scheme allowlist (control-char resistant),
+  `data:` raster-image rules, `on*`/`srcdoc` blocked, function-only handlers,
+  no `eval`, CSP- and Trusted-Types-friendly.
+- TypeScript definitions with generics for state/computed/lists.
+
+### Tooling
+- 100+ unit/DOM tests (jsdom), real-browser tests on Chromium/Firefox/WebKit
+  (Playwright), and TypeScript type tests.
+- No build step required at any point.
+
+[1.0.0]: https://github.com/Zoijs/zoijs/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Easy Framework contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Zoijs
+
+A lightweight frontend framework you don't have to learn before you use it — **plain HTML, CSS, and JavaScript**, no JSX, no build step, no Virtual DOM.
+
+**[Website](https://zoijs.com)** · **[Documentation](https://zoijs.dev)** · **[GitHub](https://github.com/Zoijs)** · **[npm](https://www.npmjs.com/package/@zoijs/core)**
+
+```bash
+npm install @zoijs/core
+```
+
+```js
+import { html, mount, createState } from "@zoijs/core";
+
+function Counter() {
+  const count = createState(0);
+  return html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`;
+}
+mount(Counter, "#app");
+```
+
+## 📚 Documentation
+
+**New here? Start at [zoijs.dev](https://zoijs.dev) (or the [docs folder](docs/README.md)) — designed to get you productive in under 30 minutes.**
+
+- [Installation](docs/installation.md) · [Your First App](docs/first-app.md) · [Core Concepts](docs/concepts/core-concepts.md)
+- [Tutorials](docs/README.md#tutorials-build-something) · [API Reference](docs/api-reference.md) · [Examples](docs/examples.md)
+- [Troubleshooting](docs/troubleshooting.md) · [FAQ](docs/faq.md) · [Migrating from React/Vue/Solid/Lit/vanilla](docs/README.md#coming-from-another-framework)
+
+---
+
+## Mission
+
+Make building modern web applications feel as approachable as writing plain HTML, CSS, and JavaScript — so that any developer, on day one, can ship real software without first learning a framework.
+
+The framework should disappear into the skills developers already have. The whole mental model is three verbs: **write a function that returns `html`, put `createState` values in it, `mount` it.**
+
+## Goals
+
+- **Beginner-friendly** — concepts you already know from vanilla JS/HTML/CSS.
+- **No build step** — runs from a single `<script type="module">`.
+- **No Virtual DOM** — fine-grained, direct DOM updates; only what changed is touched.
+- **Minimal runtime** — the browser does the heavy lifting (native `<template>`, `cloneNode`, events).
+- **Secure by default** — inert text rendering, URL-scheme guards, handler references (never strings), no `eval`.
+- **Small & readable** — a junior developer can read the source.
+
+See [`docs/Phase-1-MVP-Spec.md`](docs/Phase-1-MVP-Spec.md) for the full specification.
+
+## Setup
+
+No build step is required — the framework is plain ES modules.
+
+```bash
+# from the framework/ directory
+
+# run the counter example (serves the project root over http so ES modules resolve)
+npm run dev
+# then open: http://localhost:3000/examples/counter/   (keep the trailing slash)
+
+# run the tests (DOM tests run automatically via jsdom)
+npm test
+```
+
+> Tips:
+> - ES module imports need to be served over `http://`, not opened as a `file://` path. `npm run dev` handles that.
+> - Use the **trailing slash** on the example URL (`/examples/counter/`). Without it, some static servers resolve `./app.js` against the wrong directory and the app won't load.
+
+## Testing
+
+| Command | What it runs |
+|---|---|
+| `npm test` | Unit + DOM tests via jsdom (fast, no browser) |
+| `npm run test:unit` | Pure-logic tests only (no DOM) |
+| `npm run test:types` | TypeScript type-checks (`tsc --noEmit`) |
+| `npm run test:browser` | Real-browser tests in Chromium, Firefox, WebKit (Playwright) |
+
+Browser tests live in `browser-tests/` and run the example apps plus framework regressions against real engines. First-time setup downloads the browsers:
+
+```bash
+npm install
+npx playwright install chromium firefox webkit
+npm run test:browser
+```
+
+Playwright starts a static server automatically (`npx serve` on port 3000) — still no build step.
+
+## Browser support
+
+Modern evergreen browsers. Verified automatically (Playwright) in:
+
+| Browser | Engine | Status |
+|---|---|---|
+| Chrome / Edge | Chromium | ✅ tested |
+| Firefox | Gecko | ✅ tested |
+| Safari | WebKit | ✅ tested |
+
+Relies on baseline-modern platform APIs: ES modules, `<template>`, `TreeWalker`, `Proxy`, `queueMicrotask`, `replaceChildren`, `addEventListener`, `setAttributeNS`. No IE support, no transpilation, no polyfills.
+
+## Public API
+
+```js
+import { html, mount, createState, computed, each, configure, onCleanup } from "@zoijs/core";
+```
+
+- `html` — tagged template; parsed once, cached.
+- `mount(component, target)` — render a component; returns `unmount()`.
+- `createState(value)` — a reactive value (`get` / `set` / `peek`).
+- `computed(fn)` — a lazy, cached, **value-gated** derived value (`get` / `peek`).
+- `each(itemsFn, keyFn, renderFn)` — keyed list rendering (reuse / move / remove nodes).
+- `configure({ dev })` — toggle development warnings (default `dev: true`).
+- `onCleanup(fn)` — register teardown for a component or list item (timers, subscriptions).
+
+See the [Documentation site](docs/README.md) for the full guide, tutorials, and API reference.
+
+**TypeScript:** ships type definitions ([`src/index.d.ts`](src/index.d.ts)) for autocomplete and optional type-checking — JS-first, no build step required. `createState<T>`, `computed<T>`, and `each<T>` are generic. Type-check with `npm run test:types`.
+
+## What's built
+
+- Fine-grained text/attribute bindings — `${() => state.get()}` updates one node in place; setup runs once (no re-render).
+- Native events, secure-by-default rendering (inert text, URL-scheme guards, no `eval`).
+- `computed()` derived values — lazy, cached, nestable, and **value-gated** (unchanged results don't wake downstream).
+- `each()` keyed list reconciliation — preserves focus / input / scroll on reorder.
+- Microtask batching, push-pull dependency tracking, **owner-scoped cleanup** (unmount and removed items dispose their subscriptions).
+- Production mode via `configure({ dev: false })` — no build step.
+- Safety: self-triggering effects are warned + stopped; a throwing binding doesn't break others.
+
+**Out of scope (by design):** router, CLI, plugins, SSR, global store, TypeScript-first setup, Virtual DOM.
+
+## Project Structure
+
+```
+framework/
+  package.json
+  README.md
+  src/
+    core/
+      html.js        # html() — parse template into a cached blueprint
+      mount.js       # mount() — entry point; instantiate + attach + cleanup
+      renderer.js    # internal: bind dynamic slots, apply fine-grained updates
+    reactivity/
+      state.js       # createState() + internal dependency tracking
+    utils/
+      dom.js         # small native-DOM helpers
+      security.js    # escaping, URL-scheme allowlist, attribute-name guards
+    index.js         # public entry — re-exports html, mount, createState
+  examples/
+    counter/         # the first working app
+  tests/             # basic unit tests (node --test)
+  docs/
+    Phase-1-MVP-Spec.md
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@zoijs/core",
+  "version": "1.0.0",
+  "description": "Zoijs — a beginner-friendly, no-build, no-Virtual-DOM frontend framework. Plain HTML, CSS, and JavaScript.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Zoijs contributors (https://zoijs.com)",
+  "license": "MIT",
+  "homepage": "https://zoijs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoijs/zoijs.git",
+    "directory": "framework"
+  },
+  "bugs": {
+    "url": "https://github.com/Zoijs/zoijs/issues"
+  },
+  "keywords": [
+    "zoijs",
+    "framework",
+    "frontend",
+    "ui",
+    "reactive",
+    "reactivity",
+    "signals",
+    "no-build",
+    "no-jsx",
+    "no-virtual-dom",
+    "fine-grained",
+    "beginner-friendly",
+    "html",
+    "spa"
+  ],
+  "scripts": {
+    "test": "node --test --import ./tests/setup-dom.js \"tests/**/*.test.js\"",
+    "test:unit": "node --test \"tests/**/*.test.js\"",
+    "test:types": "tsc --noEmit -p tsconfig.json",
+    "test:browser": "playwright test",
+    "dev": "npx serve -l 3000 ."
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "jsdom": "^29.1.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/core/each.js

@@ -0,0 +1,24 @@
+// each() — keyed list rendering (Milestone 3).
+//
+// Returns a small marker object that the renderer recognizes in a text slot and
+// turns into a keyed list binding. Keeping this factory tiny (and separate from
+// the renderer) avoids a circular import — the renderer just checks the marker.
+//
+//   ${each(
+//     () => todos.get(),        // items: a reactive function (or a plain array)
+//     todo => todo.id,          // keyFn: a stable unique key per item
+//     todo => html`<li>...</li>` // renderFn: builds DOM for one item
+//   )}
+//
+// When the array changes, items with matching keys reuse their DOM nodes (moved
+// if reordered); new keys are inserted; removed keys are disposed and removed.
+
+/**
+ * @param {Function|Array} items    a function returning the array, or an array
+ * @param {Function} keyFn          item -> unique key
+ * @param {Function} renderFn       item -> html() result
+ * @returns {{ __easyEach: true, items: any, keyFn: Function, renderFn: Function }}
+ */
+export function each(items, keyFn, renderFn) {
+  return { __easyEach: true, items, keyFn, renderFn };
+}

package/src/core/html.js

@@ -0,0 +1,243 @@
+// html() — the template function.
+//
+//   html`<button onclick=${handler}>${() => count.get()}</button>`
+//
+// Parses the STATIC structure once (cached), tracking real HTML lexical context
+// with a small state machine — so it knows whether each ${} falls in text, an
+// attribute value, an event, etc. Dynamic values are kept in a separate channel
+// from the static HTML; a value can never change the template's structure.
+//
+// Output of the parse (cached per `strings`):
+//   template : a <template> element with unique markers
+//   parts    : ordered list of binding descriptors
+//      { type: "child" }                          ← a comment-marker anchor
+//      { type: "element", attrs: [AttrPart] }     ← element carrying data-zoijs-bind
+//   AttrPart : { name, strings, holes, event, whole }
+//
+// Matching is by DOCUMENT ORDER (renderer walks the clone), so markers can never
+// collide across nested templates or list items.
+
+import { createTemplate } from "../utils/dom.js";
+
+const cache = new WeakMap();
+
+/**
+ * @param {TemplateStringsArray} strings  static HTML chunks (author-controlled)
+ * @param {...any} values                 dynamic values, one per slot
+ * @returns {{ template: HTMLTemplateElement, parts: object[], values: any[] }}
+ */
+export function html(strings, ...values) {
+  let compiled = cache.get(strings);
+  if (!compiled) {
+    compiled = compile(strings);
+    cache.set(strings, compiled);
+  }
+  return { template: compiled.template, parts: compiled.parts, hasElements: compiled.hasElements, values };
+}
+
+// ---- scanner ----------------------------------------------------------------
+
+const TEXT = 0;
+const TAGNAME = 1;
+const BEFORE_ATTR = 2;
+const ATTR_NAME = 3;
+const AFTER_NAME = 4;
+const BEFORE_VAL = 5;
+const VAL_DQ = 6;
+const VAL_SQ = 7;
+const VAL_UQ = 8;
+const CLOSE_TAG = 9;
+const COMMENT = 10;
+const RAWTEXT = 11;
+
+const RAWTEXT_TAGS = new Set(["script", "style", "textarea", "title"]);
+const isWS = (c) => c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f";
+const isLetter = (c) => c >= "a" && c <= "z" || c >= "A" && c <= "Z";
+
+function unsupported(message) {
+  throw new Error(`Zoijs template: ${message}`);
+}
+
+function compile(strings) {
+  let out = "";
+  const parts = [];
+  let state = TEXT;
+
+  // current tag / attribute being built
+  let tagName = "";
+  let dynAttrs = [];
+  let selfClose = false;
+  let rawtextTag = "";
+  let attrStart = 0; // index in `out` where the current attribute's name starts
+  let attrName = "";
+  let dynamic = false; // current attribute value contains a hole
+  let strs = null; // static fragments of the current dynamic attribute value
+  let holes = null; // hole indices of the current dynamic attribute value
+  let frag = ""; // running static fragment of the current attribute value
+
+  const finalizeAttr = () => {
+    if (dynamic) {
+      strs.push(frag);
+      const whole = strs.length === 2 && strs[0] === "" && strs[1] === "";
+      let event = false;
+      if (/^on/i.test(attrName)) {
+        if (!whole) unsupported(`event handler "${attrName}" must be a single \${} value`);
+        event = true;
+      }
+      dynAttrs.push({ name: attrName, strings: strs, holes, event, whole });
+    }
+    dynamic = false;
+    strs = null;
+    holes = null;
+    frag = "";
+    attrName = "";
+  };
+
+  const finalizeTag = () => {
+    if (dynAttrs.length) {
+      out += " data-zoijs-bind";
+      parts.push({ type: "element", attrs: dynAttrs });
+    }
+    out += selfClose ? "/>" : ">";
+    const lower = tagName.toLowerCase();
+    if (RAWTEXT_TAGS.has(lower)) {
+      state = RAWTEXT;
+      rawtextTag = lower;
+    } else {
+      state = TEXT;
+    }
+    tagName = "";
+    dynAttrs = [];
+    selfClose = false;
+  };
+
+  for (let i = 0; i < strings.length; i++) {
+    const s = strings[i];
+
+    for (let k = 0; k < s.length; k++) {
+      const c = s[k];
+
+      switch (state) {
+        case TEXT:
+          if (c === "<") {
+            const nx = s[k + 1];
+            if (nx === "/") { out += "<"; state = CLOSE_TAG; }
+            else if (nx === "!") { out += "<"; state = s.substr(k + 1, 3) === "!--" ? COMMENT : CLOSE_TAG; }
+            else if (nx && isLetter(nx)) { out += "<"; state = TAGNAME; tagName = ""; dynAttrs = []; }
+            else if (nx === undefined && i < strings.length - 1) { out += "<"; state = TAGNAME; tagName = ""; dynAttrs = []; } // "<${tag}>" → clear error at the hole
+            else out += "<"; // a literal "<" in text (e.g. "a < b")
+          } else out += c;
+          break;
+
+        case TAGNAME:
+          if (isWS(c)) { out += c; state = BEFORE_ATTR; }
+          else if (c === ">") finalizeTag();
+          else if (c === "/") selfClose = true;
+          else { tagName += c; out += c; }
+          break;
+
+        case BEFORE_ATTR:
+          if (isWS(c)) out += c;
+          else if (c === ">") finalizeTag();
+          else if (c === "/") selfClose = true;
+          else { state = ATTR_NAME; attrName = c; attrStart = out.length; out += c; dynamic = false; }
+          break;
+
+        case ATTR_NAME:
+          if (c === "=") { out += c; state = BEFORE_VAL; }
+          else if (isWS(c)) { out += c; state = AFTER_NAME; }
+          else if (c === ">") finalizeTag();
+          else if (c === "/") { selfClose = true; state = AFTER_NAME; }
+          else { attrName += c; out += c; }
+          break;
+
+        case AFTER_NAME:
+          if (isWS(c)) out += c;
+          else if (c === "=") { out += c; state = BEFORE_VAL; }
+          else if (c === ">") finalizeTag();
+          else if (c === "/") selfClose = true;
+          else { state = ATTR_NAME; attrName = c; attrStart = out.length; out += c; dynamic = false; }
+          break;
+
+        case BEFORE_VAL:
+          if (isWS(c)) out += c;
+          else if (c === '"' || c === "'") { out += c; frag = ""; dynamic = false; state = c === '"' ? VAL_DQ : VAL_SQ; }
+          else { frag = c; out += c; dynamic = false; state = VAL_UQ; }
+          break;
+
+        case VAL_DQ:
+        case VAL_SQ: {
+          const q = state === VAL_DQ ? '"' : "'";
+          if (c === q) { if (dynamic) finalizeAttr(); else out += c; state = BEFORE_ATTR; }
+          else if (dynamic) frag += c;
+          else { frag += c; out += c; }
+          break;
+        }
+
+        case VAL_UQ:
+          if (isWS(c)) { if (dynamic) finalizeAttr(); out += c; state = BEFORE_ATTR; }
+          else if (c === ">") { if (dynamic) finalizeAttr(); finalizeTag(); }
+          else if (dynamic) frag += c;
+          else { frag += c; out += c; }
+          break;
+
+        case CLOSE_TAG:
+          out += c;
+          if (c === ">") state = TEXT;
+          break;
+
+        case COMMENT:
+          out += c;
+          if (c === ">" && out.endsWith("-->")) state = TEXT;
+          break;
+
+        case RAWTEXT:
+          out += c;
+          if (c === ">" && out.toLowerCase().endsWith("</" + rawtextTag + ">")) state = TEXT;
+          break;
+      }
+    }
+
+    // end of chunk → a hole (unless this was the last chunk)
+    if (i < strings.length - 1) {
+      const hole = i;
+      switch (state) {
+        case TEXT:
+          out += "<!--zoijs-->";
+          parts.push({ type: "child", hole });
+          break;
+
+        case BEFORE_VAL: // attr=${x}  → unquoted whole-value hole
+          out = out.slice(0, attrStart);
+          dynamic = true; strs = [""]; holes = [hole]; frag = "";
+          state = VAL_UQ;
+          break;
+
+        case VAL_DQ:
+        case VAL_SQ:
+        case VAL_UQ:
+          if (!dynamic) { out = out.slice(0, attrStart); dynamic = true; strs = [frag]; holes = [hole]; frag = ""; }
+          else { strs.push(frag); holes.push(hole); frag = ""; }
+          break;
+
+        case TAGNAME:
+          unsupported("dynamic tag names are not supported (e.g. `<${tag}>`)");
+        case BEFORE_ATTR:
+        case ATTR_NAME:
+        case AFTER_NAME:
+          unsupported("dynamic attribute names / spreads are not supported (e.g. `<el ${x}>`)");
+        case COMMENT:
+          unsupported("interpolation inside an HTML comment is not supported");
+        case RAWTEXT:
+          unsupported(`interpolation inside <${rawtextTag}> is not supported — set its content via a property instead`);
+        case CLOSE_TAG:
+          unsupported("interpolation inside a closing tag is not supported");
+        default:
+          unsupported("interpolation in an unsupported position");
+      }
+    }
+  }
+
+  const hasElements = parts.some((p) => p.type === "element");
+  return { template: createTemplate(out), parts, hasElements };
+}

package/src/core/mount.js

@@ -0,0 +1,31 @@
+// mount() — the single entry point that starts an app.
+//
+// Runs the component once inside a root owner scope, inserts its DOM, and returns
+// an unmount() that disposes that scope (every effect, computed, list item, and
+// event listener created under it) and detaches the DOM.
+
+import { render } from "./renderer.js";
+import { resolveTarget } from "../utils/dom.js";
+import { createOwner, runWithOwner, disposeOwner } from "../reactivity/owner.js";
+
+/**
+ * @param {Function|object} component  a component function, or an html() result
+ * @param {Element|string}  target     a DOM element or a CSS selector
+ * @returns {Function} unmount
+ */
+export function mount(component, target) {
+  const el = resolveTarget(target);
+  const owner = createOwner();
+
+  let node;
+  runWithOwner(owner, () => {
+    const result = typeof component === "function" ? component() : component;
+    node = render(result).node;
+  });
+  el.replaceChildren(node);
+
+  return () => {
+    disposeOwner(owner);
+    el.replaceChildren();
+  };
+}