@zoijs/core 1.0.0

package/src/reactivity/effect.js

@@ -0,0 +1,7 @@
+// effect() + untrack() — reactive side effects (used internally by the renderer
+// to wire bindings). An effect re-runs when something it read changes; errors it
+// throws are contained so other bindings keep working.
+//
+// Implemented by the shared reactive core (see core.js).
+
+export { effect, untrack } from "./core.js";

package/src/reactivity/env.js

@@ -0,0 +1,24 @@
+// env.js — development / production mode (Task 4).
+//
+// Development (the default) shows helpful warnings: duplicate `each` keys,
+// self-triggering effects, runaway loops. Production silences them for less
+// noise and a touch less work. No build step required — just call configure().
+//
+//   import { configure } from "@zoijs/core";
+//   configure({ dev: false }); // production
+
+let dev = true;
+
+/**
+ * @param {{ dev?: boolean }} options
+ */
+export function configure(options) {
+  if (options && typeof options.dev === "boolean") {
+    dev = options.dev;
+  }
+}
+
+/** @returns {boolean} true in development mode */
+export function isDev() {
+  return dev;
+}

package/src/reactivity/owner.js

@@ -0,0 +1,61 @@
+// owner.js — ownership scopes for deterministic cleanup (Task 2).
+//
+// An owner collects "disposers" — functions that tear down whatever was created
+// inside its scope (effects, computeds, event listeners, list-item subtrees).
+// Owners nest: disposing a parent disposes its children first. This is how
+// unmount() and removed list items free their reactive subscriptions instead of
+// leaving them attached to long-lived state.
+//
+// These are internal helpers (not part of the public API).
+
+let currentOwner = null;
+
+/** The active owner, or null outside any scope. */
+export function getOwner() {
+  return currentOwner;
+}
+
+/** Create a scope, nested under the currently active owner. */
+export function createOwner() {
+  const owner = {
+    disposers: [],
+    children: new Set(),
+    parent: currentOwner,
+    disposed: false,
+  };
+  if (currentOwner) currentOwner.children.add(owner);
+  return owner;
+}
+
+/** Run `fn` with `owner` active, so things it creates register into `owner`. */
+export function runWithOwner(owner, fn) {
+  const previous = currentOwner;
+  currentOwner = owner;
+  try {
+    return fn();
+  } finally {
+    currentOwner = previous;
+  }
+}
+
+/** Register a cleanup function in the active owner (no-op outside a scope). */
+export function onCleanup(fn) {
+  if (currentOwner) currentOwner.disposers.push(fn);
+}
+
+/** Dispose a scope: tear down child scopes first, then run its disposers. */
+export function disposeOwner(owner) {
+  if (owner.disposed) return;
+  owner.disposed = true;
+  for (const child of [...owner.children]) disposeOwner(child);
+  owner.children.clear();
+  for (let i = owner.disposers.length - 1; i >= 0; i--) {
+    try {
+      owner.disposers[i]();
+    } catch (err) {
+      console.error("Zoijs: a cleanup handler threw:", err);
+    }
+  }
+  owner.disposers.length = 0;
+  if (owner.parent) owner.parent.children.delete(owner);
+}

package/src/reactivity/scheduler.js

@@ -0,0 +1,7 @@
+// flush() — force the batched effect queue to run now (used by tests and by code
+// that needs a synchronous DOM update before measuring). Updates normally flush
+// automatically on a microtask.
+//
+// Implemented by the shared reactive core (see core.js).
+
+export { flush } from "./core.js";

package/src/reactivity/state.js

@@ -0,0 +1,10 @@
+// createState() — the reactive value primitive.
+//
+//   const count = createState(0);
+//   count.get();   // read  (subscribes the running effect/computed)
+//   count.set(1);  // write (wakes subscribers, only if the value changed)
+//   count.peek();  // read without subscribing
+//
+// Implemented by the shared reactive core (see core.js).
+
+export { createState } from "./core.js";

package/src/utils/dom.js

@@ -0,0 +1,51 @@
+// dom.js — small helpers over native DOM APIs.
+//
+// Intentionally thin: the framework prefers using the platform directly.
+
+/**
+ * Resolve a target that may be an element or a CSS selector string.
+ * @param {Element|string} target
+ * @returns {Element}
+ */
+export function resolveTarget(target) {
+  const el = typeof target === "string" ? document.querySelector(target) : target;
+  if (!el) {
+    throw new Error(`Zoijs: mount target not found: ${String(target)}`);
+  }
+  return el;
+}
+
+// Trusted Types support. `template.innerHTML = string` is a Trusted-Types sink,
+// so under a strict `require-trusted-types-for 'script'` CSP it would throw. The
+// htmlText here is ALWAYS framework-generated from the author's static template
+// strings + markers — dynamic values never reach it (the scanner forbids that) —
+// so a pass-through policy is safe by construction. Pages enforcing Trusted Types
+// must allow the `zoijs` policy (e.g. `trusted-types zoijs`).
+let ttPolicy;
+let ttChecked = false;
+function trustedHTML(htmlText) {
+  if (!ttChecked) {
+    ttChecked = true;
+    try {
+      const tt = typeof window !== "undefined" ? window.trustedTypes : undefined;
+      if (tt && tt.createPolicy) {
+        ttPolicy = tt.createPolicy("zoijs", { createHTML: (s) => s });
+      }
+    } catch {
+      ttPolicy = undefined; // policy name unavailable; fall back
+    }
+  }
+  return ttPolicy ? ttPolicy.createHTML(htmlText) : htmlText;
+}
+
+/**
+ * Build an inert <template> from an HTML string and return the element.
+ * Parsing happens inside <template>, so no scripts run and no resources load.
+ * @param {string} htmlText
+ * @returns {HTMLTemplateElement}
+ */
+export function createTemplate(htmlText) {
+  const template = document.createElement("template");
+  template.innerHTML = trustedHTML(htmlText);
+  return template;
+}

package/src/utils/security.js

@@ -0,0 +1,55 @@
+// security.js — secure-by-default helpers.
+//
+// These are NOT optional add-ons; the renderer routes every dynamic value
+// through them so the safe path is the default path. See docs/security.md.
+
+/**
+ * Coerce a value to a string for safe insertion as TEXT.
+ * Text slots are written via a Text node (inert), so this is just predictable
+ * coercion: null/undefined become "".
+ * @param {any} value
+ * @returns {string}
+ */
+export function toText(value) {
+  return value === null || value === undefined ? "" : String(value);
+}
+
+// Allowlisted URL schemes for URL-bearing attributes (href, src, ...).
+const SAFE_SCHEMES = new Set(["http", "https", "mailto", "tel"]);
+// data: is allowed only for raster image MIME types (never text/html, never SVG,
+// which can carry script when navigated to).
+const SAFE_DATA_IMAGE = /^data:image\/(png|jpe?g|gif|webp|avif|bmp|x-icon)[;,]/;
+
+/**
+ * Is this URL safe for a URL-bearing attribute (href, src, action, ...)?
+ * Relative URLs (no scheme) are allowed; otherwise only an allowlist of schemes.
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isSafeUrl(url) {
+  // Browsers strip ASCII control characters (incl. TAB/CR/LF) before parsing a
+  // URL, so "java\tscript:alert(1)" becomes "javascript:". Strip them first, or
+  // the scheme check can be bypassed.
+  const cleaned = String(url).replace(/[\x00-\x1F]/g, "").trim();
+  const match = cleaned.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+  if (!match) return true; // relative URL (no scheme) — safe
+  const scheme = match[1].toLowerCase();
+  if (scheme === "data") return SAFE_DATA_IMAGE.test(cleaned.toLowerCase());
+  return SAFE_SCHEMES.has(scheme);
+}
+
+// Attribute names that must never be bound from data.
+const DANGEROUS_ATTRS = new Set(["srcdoc"]); // iframe srcdoc = raw-HTML sink
+
+/**
+ * Reject attribute names that should never be bound from data: inline event
+ * handlers (`on*`, which have their own safe path) and raw-HTML sinks (`srcdoc`).
+ * @param {string} name
+ * @returns {boolean} true if the attribute name is allowed
+ */
+export function isSafeAttributeName(name) {
+  const lower = name.toLowerCase();
+  if (lower.startsWith("on")) return false;
+  if (DANGEROUS_ATTRS.has(lower)) return false;
+  return true;
+}