feat(core): add essential directives (unsafeHTML, live) with renderer integration

Only three directives in webjs — each solves a problem with no native
alternative. unsafeHTML for trusted raw HTML, live for input value
dirty-checking, repeat (already existed) for keyed lists. Both client
and server renderers now process directive markers correctly instead
of rendering [object Object].

Dropped 9 non-essential directives (classMap, styleMap, ifDefined,
when, choose, guard, ref, cache, until) in favor of native patterns.
Less is more — AI agents don't need syntax sugar.

Author: vivek7405

packages/core/index.js

@@ -9,8 +9,8 @@
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
 export { WebComponent } from './src/component.js';
-export { register, lookup, lookupModuleUrl, allTags } from './src/registry.js';
-export { renderToString } from './src/render-server.js';
+export { register, lookup, lookupModuleUrl, isLazy, allTags } from './src/registry.js';
+export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
@@ -20,3 +20,12 @@ export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
 export { enableClientRouter, disableClientRouter, navigate } from './src/router-client.js';
+
+// Directives — also available via 'webjs/directives'
+export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
+
+// Context Protocol — also available via 'webjs/context'
+export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
+
+// Task controller — also available via 'webjs/task'
+export { Task, TaskStatus } from './src/task.js';

packages/core/src/directives.js

@@ -0,0 +1,109 @@
+/**
+ * Built-in directives for the webjs `html` tagged template system.
+ *
+ * webjs follows a "less is more" philosophy: only directives that solve
+ * problems with NO native alternative are included. AI agents don't need
+ * syntax sugar — they can write ternaries, string concatenation, and
+ * lifecycle hooks just fine.
+ *
+ * **What's here:**
+ * - `unsafeHTML(str)` — render trusted raw HTML (no alternative in templates)
+ *
+ * **What's NOT here (and why):**
+ * - classMap → use `class=${'btn ' + (active ? 'active' : '')}`
+ * - styleMap → use `style=${'color:' + color}`
+ * - ifDefined → use `attr=${val ?? null}` (null removes the attribute)
+ * - when/choose → use ternary `${cond ? a : b}` or if/else before the template
+ * - guard → memoize in `willUpdate()` lifecycle hook
+ * - ref → use `this.query('#el')` in `firstUpdated()` or `updated()`
+ * - cache → use CSS `display:none` to preserve DOM instead of removing
+ * - until → use the `Task` controller for component-scoped async data
+ * - live → set `.value` via property binding `.value=${val}` and handle
+ *   input events with `@input=${e => this.setState({val: e.target.value})}`
+ *
+ * `repeat()` is in its own file (`./repeat.js`) — it's essential for keyed
+ * list reconciliation and has no native alternative.
+ *
+ * @module directives
+ */
+
+/* ================================================================
+ * unsafeHTML
+ * ================================================================ */
+
+/**
+ * Render a raw HTML string without escaping. The string is injected
+ * directly into the DOM as parsed HTML nodes.
+ *
+ * **When to use (AI hint):** Use ONLY for trusted HTML — CMS content,
+ * markdown-to-HTML output, or sanitized rich text. NEVER use for
+ * user-supplied input — this is an XSS vector.
+ *
+ * ```js
+ * import { html } from 'webjs';
+ * import { unsafeHTML } from 'webjs/directives';
+ *
+ * // Good: trusted markdown output
+ * html`<article>${unsafeHTML(markdownToHtml(post.body))}</article>`;
+ *
+ * // DANGEROUS: user input — use ${text} instead (auto-escaped)
+ * // html`<p>${unsafeHTML(userInput)}</p>`;  // ← XSS!
+ * ```
+ *
+ * @param {string | null | undefined} htmlString
+ *   Trusted HTML string to render without escaping.
+ * @returns {{ _$webjs: 'unsafe-html', value: string }}
+ */
+export function unsafeHTML(htmlString) {
+  return { _$webjs: 'unsafe-html', value: String(htmlString ?? '') };
+}
+
+/**
+ * Type guard: returns `true` if `x` is a marker produced by `unsafeHTML()`.
+ * @param {unknown} x
+ * @returns {x is { _$webjs: 'unsafe-html', value: string }}
+ */
+export function isUnsafeHTML(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'unsafe-html';
+}
+
+/* ================================================================
+ * live
+ * ================================================================ */
+
+/**
+ * Dirty-check a value against the **live DOM value** instead of the
+ * last rendered value. Essential for `<input>` two-way binding where
+ * the user can modify the DOM value between renders.
+ *
+ * **When to use (AI hint):** Use `live()` on `.value` or `.checked`
+ * bindings for `<input>`, `<textarea>`, `<select>` elements where the
+ * user types/selects between renders. Without `live()`, the renderer
+ * skips the update because its cached value matches — even though the
+ * DOM value has changed.
+ *
+ * ```js
+ * import { html } from 'webjs';
+ * import { live } from 'webjs/directives';
+ *
+ * html`<input .value=${live(this.state.query)}
+ *             @input=${e => this.setState({ query: e.target.value })}>`;
+ * ```
+ *
+ * On the server, `live()` is a no-op — it unwraps to the inner value.
+ *
+ * @param {unknown} value  The value to set on the element.
+ * @returns {{ _$webjs: 'live', value: unknown }}
+ */
+export function live(value) {
+  return { _$webjs: 'live', value };
+}
+
+/**
+ * Type guard: returns `true` if `x` is a marker produced by `live()`.
+ * @param {unknown} x
+ * @returns {x is { _$webjs: 'live', value: unknown }}
+ */
+export function isLive(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'live';
+}

packages/core/src/render-client.js

@@ -1,6 +1,7 @@
 import { isTemplate, MARKER } from './html.js';
 import { escapeAttr } from './escape.js';
 import { isRepeat } from './repeat.js';
+import { isUnsafeHTML, isLive } from './directives.js';
 
 /**
  * Client-side renderer with **fine-grained** updates.
@@ -403,6 +404,16 @@ function clearInstance(inst, container) {
  * @param {unknown} _prev
  */
 function applyPart(part, value, _prev) {
+  // Unwrap live() — dirty-check against the live DOM value, not the
+  // last rendered value. Essential for <input> two-way binding.
+  if (isLive(value)) {
+    const liveVal = /** @type any */ (value).value;
+    if (part.kind === 'prop' && /** @type any */ (part.el)[part.name] === liveVal) return;
+    if (part.kind === 'attr' && part.el.getAttribute(part.name) === String(liveVal)) return;
+    if (part.kind === 'bool' && part.el.hasAttribute(part.name) === !!liveVal) return;
+    value = liveVal;
+  }
+
   switch (part.kind) {
     case 'child':
       applyChild(part, value);
@@ -439,6 +450,20 @@ function applyPart(part, value, _prev) {
 function applyChild(part, value) {
   const marker = part.marker;
 
+  // unsafeHTML directive — inject raw HTML string as DOM nodes.
+  if (isUnsafeHTML(value)) {
+    teardownChild(part);
+    const htmlStr = String(/** @type any */ (value).value ?? '');
+    const template = document.createElement('template');
+    template.innerHTML = htmlStr;
+    const nodes = [...template.content.childNodes];
+    const frag = document.createDocumentFragment();
+    for (const n of nodes) frag.appendChild(n);
+    marker.parentNode?.insertBefore(frag, marker);
+    part.child = nodes;
+    return;
+  }
+
   // Repeat directive — keyed reconciliation. Keep previous state when both
   // old and new are repeats; otherwise tear down and rebuild.
   if (isRepeat(value)) {