blokd 0.1.0-beta.0

package/src/resume.ts

@@ -0,0 +1,274 @@
+import { jsx, type Renderable } from './jsx-runtime.js';
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export type ResumableRef = `${string}#${string}` | string;
+
+export type ResumeContext<TState = JsonValue> = {
+  event: Event;
+  element: Element;
+  island: Element | null;
+  state: TState | null;
+  setState(next: TState | ((previous: TState | null) => TState)): void;
+  ref: string;
+};
+
+export type ResumableEventHandler<TState = JsonValue> = (
+  event: Event,
+  ctx: ResumeContext<TState>
+) => unknown | Promise<unknown>;
+
+export type ResumableHandler<TState = JsonValue> = {
+  readonly __blokdResumable: true;
+  readonly ref: string;
+  readonly handler?: ResumableEventHandler<TState>;
+};
+
+export type IslandProps<TState extends JsonValue = JsonValue> = {
+  name: string;
+  state?: TState;
+  id?: string;
+  as?: string;
+  children?: Renderable;
+};
+
+export type StartResumabilityOptions = {
+  root?: Document | Element;
+  events?: readonly string[];
+  /**
+   * Production safety valve. Return false to reject a data-blokd-on* ref before dynamic import.
+   */
+  allowRef?: (ref: string) => boolean;
+  onError?: (error: unknown, ctx: Omit<ResumeContext, 'state' | 'setState'>) => void;
+};
+
+const registry = new Map<string, ResumableEventHandler>();
+const inflight = new Map<string, Promise<ResumableEventHandler>>();
+const DEFAULT_EVENTS = ['click', 'input', 'change', 'submit'] as const;
+type RootTarget = Document | Element;
+type ListenerRecord = { listener: EventListener; count: number };
+type RootResumabilityState = {
+  options: StartResumabilityOptions;
+  listeners: Map<string, ListenerRecord>;
+};
+const rootStates = new WeakMap<RootTarget, RootResumabilityState>();
+
+export function resumable<TState = JsonValue>(
+  ref: ResumableRef,
+  handler?: ResumableEventHandler<TState>
+): ResumableHandler<TState> {
+  const normalized = String(ref);
+  assertValidRef(normalized);
+  if (handler) {
+    registry.set(normalized, handler as unknown as ResumableEventHandler);
+    return { __blokdResumable: true, ref: normalized, handler };
+  }
+  return { __blokdResumable: true, ref: normalized };
+}
+
+export function isResumableHandler(value: unknown): value is ResumableHandler {
+  return !!value && typeof value === 'object' && (value as ResumableHandler).__blokdResumable === true;
+}
+
+export function registerResumable<TState = JsonValue>(ref: ResumableRef, handler: ResumableEventHandler<TState>): void {
+  const normalized = String(ref);
+  assertValidRef(normalized);
+  registry.set(normalized, handler as unknown as ResumableEventHandler);
+}
+
+export function unregisterResumable(ref: ResumableRef): void {
+  registry.delete(String(ref));
+  inflight.delete(String(ref));
+}
+
+export function Island<TState extends JsonValue = JsonValue>(props: IslandProps<TState>): Renderable {
+  const tag = props.as ?? 'div';
+  validateIslandTag(tag);
+  const attrs: Record<string, unknown> = {
+    'data-blokd-island': props.name,
+    children: props.children
+  };
+  if (props.id) attrs.id = props.id;
+  if (props.state !== undefined) attrs['data-blokd-state'] = serializeState(props.state);
+  return jsx(tag, attrs);
+}
+
+export function eventAttributeName(eventName: string): string {
+  if (!/^[a-z][a-z0-9_-]*$/i.test(eventName)) throw new Error(`Invalid event name: ${eventName}`);
+  return `data-blokd-on${eventName.toLowerCase()}`;
+}
+
+export function serializeState(value: JsonValue): string {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) return 'null';
+  return serialized
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026')
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029');
+}
+
+export function parseState<TState = JsonValue>(value: string | null): TState | null {
+  if (!value) return null;
+  try {
+    return JSON.parse(value) as TState;
+  } catch {
+    return null;
+  }
+}
+
+export function startResumability(options: StartResumabilityOptions = {}): () => void {
+  if (typeof document === 'undefined') return () => undefined;
+  const root = options.root ?? document;
+  const events = Array.from(new Set(options.events ?? DEFAULT_EVENTS));
+  let state = rootStates.get(root);
+  if (!state) {
+    state = { options, listeners: new Map() };
+    rootStates.set(root, state);
+  }
+  state.options = options;
+
+  for (const eventName of events) {
+    eventAttributeName(eventName);
+    let record = state.listeners.get(eventName);
+    if (!record) {
+      const listener: EventListener = event => {
+        const latest = rootStates.get(root);
+        if (latest) void dispatchResumableEvent(event, latest.options);
+      };
+      root.addEventListener(eventName, listener, true);
+      record = { listener, count: 0 };
+      state.listeners.set(eventName, record);
+    }
+    record.count++;
+  }
+
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    const current = rootStates.get(root);
+    if (!current) return;
+    for (const eventName of events) {
+      const record = current.listeners.get(eventName);
+      if (!record) continue;
+      record.count--;
+      if (record.count <= 0) {
+        root.removeEventListener(eventName, record.listener, true);
+        current.listeners.delete(eventName);
+      }
+    }
+    if (current.listeners.size === 0) rootStates.delete(root);
+  };
+}
+
+async function dispatchResumableEvent(event: Event, options: StartResumabilityOptions): Promise<void> {
+  const match = findResumableElement(event);
+  if (!match) return;
+
+  const { element, ref } = match;
+  const island = element.closest('[data-blokd-island]');
+  const baseCtx = { event, element, island, ref };
+
+  try {
+    if (options.allowRef && !options.allowRef(ref)) throw new Error(`Blokd resumable ref rejected by allowRef(): ${ref}`);
+    if (!isSafeDynamicRef(ref)) throw new Error(`Unsafe Blokd resumable ref: ${ref}`);
+    const handler = await loadHandler(ref);
+    const ctx = createResumeContext(baseCtx);
+    await handler(event, ctx);
+  } catch (error) {
+    if (options.onError) options.onError(error, baseCtx);
+    else setTimeout(() => { throw error; }, 0);
+  }
+}
+
+function findResumableElement(event: Event): { element: Element; ref: string } | null {
+  const attr = eventAttributeName(event.type);
+  const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+  for (const item of path) {
+    if (!(item instanceof Element)) continue;
+    const ref = item.getAttribute(attr);
+    if (ref) return { element: item, ref };
+  }
+
+  const target = event.target;
+  if (!(target instanceof Element)) return null;
+  const element = target.closest(`[${attr}]`);
+  const ref = element?.getAttribute(attr);
+  return element && ref ? { element, ref } : null;
+}
+
+function createResumeContext(base: Omit<ResumeContext, 'state' | 'setState'>): ResumeContext {
+  const getStateElement = () => base.island ?? base.element;
+  const read = () => parseState(getStateElement().getAttribute('data-blokd-state'));
+  return {
+    ...base,
+    get state() {
+      return read();
+    },
+    setState(next) {
+      const previous = read();
+      const value = typeof next === 'function' ? (next as (previous: JsonValue | null) => JsonValue)(previous) : next;
+      getStateElement().setAttribute('data-blokd-state', serializeState(value));
+    }
+  } as ResumeContext;
+}
+
+async function loadHandler(ref: string): Promise<ResumableEventHandler> {
+  const registered = registry.get(ref);
+  if (registered) return registered;
+  const active = inflight.get(ref);
+  if (active) return active;
+
+  const promise = importHandler(ref);
+  inflight.set(ref, promise);
+  try {
+    const handler = await promise;
+    registry.set(ref, handler);
+    return handler;
+  } finally {
+    inflight.delete(ref);
+  }
+}
+
+async function importHandler(ref: string): Promise<ResumableEventHandler> {
+  const { moduleId, exportName } = parseRef(ref);
+  const mod = await import(/* @vite-ignore */ moduleId) as Record<string, unknown>;
+  const handler = mod[exportName];
+  if (typeof handler !== 'function') {
+    throw new Error(`Blokd resumable handler ${exportName} was not found in ${moduleId}.`);
+  }
+  return handler as ResumableEventHandler;
+}
+
+function parseRef(ref: string): { moduleId: string; exportName: string } {
+  const index = ref.lastIndexOf('#');
+  if (index <= 0 || index === ref.length - 1) {
+    throw new Error(`Invalid Blokd resumable ref: ${ref}. Expected "module#export".`);
+  }
+  return { moduleId: ref.slice(0, index), exportName: ref.slice(index + 1) };
+}
+
+function assertValidRef(ref: string): void {
+  parseRef(ref);
+  if (!isSafeDynamicRef(ref)) throw new Error(`Unsafe Blokd resumable ref: ${ref}`);
+}
+
+function isSafeDynamicRef(ref: string): boolean {
+  const { moduleId } = parseRef(ref);
+  const lowered = moduleId.trim().toLowerCase();
+  if (lowered.startsWith('javascript:') || lowered.startsWith('data:') || lowered.startsWith('blob:')) return false;
+  if (/^https?:\/\//.test(lowered)) {
+    if (typeof location === 'undefined') return false;
+    try { return new URL(moduleId, location.href).origin === location.origin; }
+    catch { return false; }
+  }
+  return true;
+}
+
+function validateIslandTag(tag: string): void {
+  if (!/^[a-z][a-z0-9.-]*$/i.test(tag)) throw new Error(`Invalid Island tag: ${tag}`);
+  if (tag.toLowerCase() === 'script') throw new Error('Island cannot render as <script>.');
+}

package/src/server.ts

@@ -0,0 +1,241 @@
+import { runWithEffectsDisabled } from './core.js';
+import { isLazy, type Renderable, type VElement, type VFragment, type Dynamic } from './jsx-runtime.js';
+import { eventAttributeName, isResumableHandler } from './resume.js';
+
+export type MetaDescriptor = {
+  title?: string;
+  description?: string;
+  htmlAttrs?: Record<string, string | number | bigint | boolean | null | undefined>;
+  bodyAttrs?: Record<string, string | number | bigint | boolean | null | undefined>;
+  meta?: Array<Record<string, string | number | boolean>>;
+  links?: Array<Record<string, string | number | boolean>>;
+  scripts?: Array<Record<string, string | number | boolean>>;
+};
+
+export type ResponseLike = Response | Renderable | string | number | bigint | boolean | null | undefined;
+
+export class HttpError extends Error {
+  readonly response: Response;
+  constructor(response: Response) {
+    super(`${response.status} ${response.statusText}`.trim());
+    this.name = 'HttpError';
+    this.response = response;
+  }
+}
+
+export class Redirect extends HttpError {
+  constructor(location: string, status = 302) {
+    validateRedirect(location, status);
+    super(new Response(null, { status, headers: { location } }));
+    this.name = 'Redirect';
+  }
+}
+
+export function redirect(location: string, status = 302): never {
+  throw new Redirect(location, status);
+}
+
+export function notFound(message = 'Not Found'): never {
+  throw new HttpError(new Response(message, { status: 404, statusText: 'Not Found' }));
+}
+
+export function httpError(status: number, message?: string, init?: ResponseInit): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) throw new Error(`httpError() requires a 4xx or 5xx status. Received ${status}.`);
+  throw new HttpError(new Response(message ?? defaultStatusText(status), { ...init, status }));
+}
+
+export function isHttpError(error: unknown): error is HttpError {
+  return error instanceof HttpError;
+}
+
+export function json(data: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has('content-type')) headers.set('content-type', 'application/json; charset=utf-8');
+  return new Response(JSON.stringify(data) ?? 'null', { ...init, headers });
+}
+
+export function html(body: string, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  if (!headers.has('content-type')) headers.set('content-type', 'text/html; charset=utf-8');
+  return new Response(body, { ...init, headers });
+}
+
+export function escapeHtml(value: unknown): string {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+export function safeJsonScript(data: unknown): string {
+  return (JSON.stringify(data) ?? 'null')
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e')
+    .replaceAll('&', '\\u0026')
+    .replaceAll('\u2028', '\\u2028')
+    .replaceAll('\u2029', '\\u2029');
+}
+
+export function renderToString(input: Renderable | (() => Renderable)): string {
+  return runWithEffectsDisabled(() => renderValue(typeof input === 'function' ? (input as () => Renderable)() : input));
+}
+
+function renderValue(value: Renderable): string {
+  if (value === null || value === undefined || value === false || value === true) return '';
+  if (Array.isArray(value)) return value.map(renderValue).join('');
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'bigint') return escapeHtml(value);
+  if (isLazy(value)) return renderValue(value.fn() as Renderable);
+  if (typeof Node !== 'undefined' && value instanceof Node) return escapeHtml(value.textContent ?? '');
+  if (typeof value === 'object' && value && 'kind' in value) {
+    const kind = (value as { kind: string }).kind;
+    if (kind === 'element') return renderElement(value as VElement);
+    if (kind === 'fragment') return renderFragment(value as VFragment);
+    if (kind === 'dynamic') return renderValue((value as Dynamic).fn() as Renderable);
+  }
+  return escapeHtml(String(value));
+}
+
+const voidElements = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr']);
+const rawTextElements = new Set(['script', 'style']);
+const blockedAttrs = new Set(['innerHTML', 'outerHTML']);
+
+function renderElement(element: VElement): string {
+  const attrs = renderAttrs(element.props);
+  if (voidElements.has(element.tag)) return `<${element.tag}${attrs}>`;
+  const children = rawTextElements.has(element.tag)
+    ? element.children.map(child => child == null ? '' : String(resolveOnce(child))).join('')
+    : element.children.map(renderValue).join('');
+  return `<${element.tag}${attrs}>${children}</${element.tag}>`;
+}
+
+function renderFragment(fragment: VFragment): string {
+  return fragment.children.map(renderValue).join('');
+}
+
+function resolveOnce(value: Renderable): unknown {
+  if (isLazy(value)) return value.fn();
+  return value;
+}
+
+function renderAttrs(props: Record<string, unknown>): string {
+  let out = '';
+  const explicitClass = props.class ?? props.className;
+  const classList = props.classList;
+  const classListValue = classList && typeof classList === 'object'
+    ? Object.entries(classList as Record<string, unknown>)
+      .filter(([, v]) => Boolean(isLazy(v) ? v.fn() : v))
+      .map(([k]) => k)
+      .join(' ')
+    : '';
+
+  for (const [rawName, rawValue] of Object.entries(props)) {
+    if (rawName === 'children' || rawName === 'ref' || rawName === 'classList') continue;
+    if (blockedAttrs.has(rawName)) throw new Error(`Blokd blocks ${rawName} during SSR. Use text children or an explicit sanitization boundary.`);
+    const eventMatch = /^on([A-Z].*|[a-z].*)$/.exec(rawName);
+    if (eventMatch) {
+      const value = isLazy(rawValue) ? rawValue.fn() : rawValue;
+      if (isResumableHandler(value)) out += ` ${eventAttributeName(eventMatch[1]!.toLowerCase())}="${escapeHtml(value.ref)}"`;
+      continue;
+    }
+    const name = rawName === 'className' ? 'class' : rawName;
+    let value = isLazy(rawValue) ? rawValue.fn() : rawValue;
+    if (name === 'class' && classListValue) value = [value, classListValue].filter(Boolean).join(' ');
+    if (value === false || value === null || value === undefined) continue;
+    if (value === true) {
+      out += ` ${escapeHtml(name)}`;
+      continue;
+    }
+    if (name === 'style' && value && typeof value === 'object') {
+      const style = Object.entries(value as Record<string, unknown>)
+        .filter(([, v]) => v !== null && v !== undefined && v !== false)
+        .map(([k, v]) => `${k}:${String(isLazy(v) ? v.fn() : v)}`)
+        .join(';');
+      if (style) out += ` style="${escapeHtml(style)}"`;
+      continue;
+    }
+    out += ` ${escapeHtml(name)}="${escapeHtml(value)}"`;
+  }
+
+  if (classListValue && explicitClass === undefined) out += ` class="${escapeHtml(classListValue)}"`;
+  return out;
+}
+
+export function renderDocument(options: {
+  body: Renderable | (() => Renderable);
+  data?: unknown;
+  meta?: MetaDescriptor;
+  status?: number;
+  headers?: HeadersInit;
+  entryClient?: string;
+}): Response {
+  const meta = options.meta ?? {};
+  const htmlAttrs = attrsToString(meta.htmlAttrs ?? { lang: 'en' });
+  const bodyAttrs = attrsToString(meta.bodyAttrs ?? {});
+  const head = renderHead(meta);
+  const body = renderToString(options.body);
+  const data = options.data === undefined ? '' : `<script id="__BLOKD_DATA__" type="application/json">${safeJsonScript(options.data)}</script>`;
+  const client = options.entryClient ? `<script type="module" src="${escapeHtml(options.entryClient)}"></script>` : '';
+  const init: ResponseInit = { status: options.status ?? 200 };
+  if (options.headers !== undefined) init.headers = options.headers;
+  return html(`<!doctype html><html${htmlAttrs}><head>${head}</head><body${bodyAttrs}>${body}${data}${client}</body></html>`, init);
+}
+
+export function renderHead(meta: MetaDescriptor): string {
+  const pieces: string[] = ['<meta charset="utf-8">', '<meta name="viewport" content="width=device-width, initial-scale=1">'];
+  if (meta.title) pieces.push(`<title>${escapeHtml(meta.title)}</title>`);
+  if (meta.description) pieces.push(`<meta name="description" content="${escapeHtml(meta.description)}">`);
+  for (const item of meta.meta ?? []) pieces.push(`<meta${attrsToString(item)}>`);
+  for (const item of meta.links ?? []) pieces.push(`<link${attrsToString(item)}>`);
+  for (const item of meta.scripts ?? []) pieces.push(`<script${attrsToString(item)}></script>`);
+  return pieces.join('');
+}
+
+export function mergeMeta(...metas: Array<MetaDescriptor | null | undefined>): MetaDescriptor {
+  const out: MetaDescriptor = { htmlAttrs: {}, bodyAttrs: {}, meta: [], links: [], scripts: [] };
+  for (const meta of metas) {
+    if (!meta) continue;
+    if (meta.title !== undefined) out.title = meta.title;
+    if (meta.description !== undefined) out.description = meta.description;
+    out.htmlAttrs = { ...(out.htmlAttrs ?? {}), ...(meta.htmlAttrs ?? {}) };
+    out.bodyAttrs = { ...(out.bodyAttrs ?? {}), ...(meta.bodyAttrs ?? {}) };
+    out.meta = [...(out.meta ?? []), ...(meta.meta ?? [])];
+    out.links = [...(out.links ?? []), ...(meta.links ?? [])];
+    out.scripts = [...(out.scripts ?? []), ...(meta.scripts ?? [])];
+  }
+  return out;
+}
+
+export function attrsToString(attrs: Record<string, string | number | bigint | boolean | null | undefined>): string {
+  let out = '';
+  for (const [name, value] of Object.entries(attrs)) {
+    if (value === false || value === null || value === undefined) continue;
+    if (value === true) out += ` ${escapeHtml(name)}`;
+    else out += ` ${escapeHtml(name)}="${escapeHtml(value)}"`;
+  }
+  return out;
+}
+
+function validateRedirect(location: string, status: number): void {
+  if (!/^(301|302|303|307|308)$/.test(String(status))) throw new Error(`redirect() status must be one of 301, 302, 303, 307, or 308. Received ${status}.`);
+  if (/\r|\n/.test(location)) throw new Error('redirect() location must not contain CR or LF characters.');
+}
+
+function defaultStatusText(status: number): string {
+  const map: Record<number, string> = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    409: 'Conflict',
+    422: 'Unprocessable Content',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout'
+  };
+  return map[status] ?? 'Error';
+}