@excom/quark 0.1.0

package/src/constants.ts

@@ -0,0 +1,47 @@
+/**
+ * Mutation kind queued on the parent when elements are removed below it.
+ * Only rules whose match depends on children or sibling position react
+ * (`Rule.reactsToRemovals`). A sheet observes removals only if a rule
+ * does.
+ */
+export const CHILD_REMOVED = "CHILD_REMOVED";
+
+// names Quark never observes (engine markers, inline style, the `content` key);
+// `class` / `id` are observed (`.x` / `#x` gate like attributes)
+export const ATTRIBUTE_BLACKLIST_REGEXES = [
+  /^q-/,
+  /^n-/,
+  /^style$/,
+  /^content$/,
+];
+
+/*
+ * What an expression result does. Kept here so resolvers stay dumb:
+ *
+ * - wipe: remove the attr / clear content. `undefined` wipes too. A
+ *   declaration that resolves to nothing clears its target (fresh over
+ *   stale).
+ * - no-op: leave the target as-is. Opt-in via `preserve` (`content:
+ *   $todo.title or preserve;` for loading). Failed evals also no-op,
+ *   never wipe.
+ * - unset: variables only. Deletes the binding so descendants fall
+ *   through (CSS `unset` / inherit). On attr / content it degrades to a
+ *   wipe.
+ */
+export const SYMBOL_NOOP = Symbol("preserve");
+export const SYMBOL_UNSET = Symbol("unset");
+
+export const TYPES_WIPE: unknown[] = [undefined, null, SYMBOL_UNSET];
+
+export const TYPES_NOOP: unknown[] = [SYMBOL_NOOP];
+
+/** Keyword → value bindings available in every expression scope. */
+export const VALUE_MAP = {
+  none: null,
+  preserve: SYMBOL_NOOP,
+  unset: SYMBOL_UNSET,
+};
+
+export const isWipe = (value: unknown): boolean => TYPES_WIPE.includes(value);
+
+export const isNoop = (value: unknown): boolean => TYPES_NOOP.includes(value);

package/src/cycle-check.ts

@@ -0,0 +1,121 @@
+/**
+ * Static write-cycle warning, once per sheet at construction.
+ *
+ * A rule's selector gates on attrs (`[is-open]`, `:not([x])`, a literal
+ * `attr("x")` read) and its declarations write attrs. If A writes what
+ * B gates on and B writes what A gates on, they can re-trigger each
+ * other. Cycles that settle (Quark skips equal writes) are fine; ones
+ * that don't get cut by the loop guard. Still worth naming at build,
+ * once, with the rules involved.
+ *
+ * Self-edges (`input[value] { value: … }`) are the usual idempotent
+ * idiom and are not reported. `content`, `dataset`, `ariaset`, `class`,
+ * and `--custom-property` do not name an attr and are ignored. `@on`
+ * block rules never run in passes and are skipped.
+ */
+import { StyleProperty } from "./properties";
+import type { Quark } from "./quark";
+import type { Rule } from "./rule";
+import { QuarkLogger } from "./utils";
+import { LoopGuard } from "@excom/kit-utils";
+
+const NON_ATTRIBUTE_KEYS = new Set(["content", "dataset", "ariaset", "class"]);
+
+/** Attribute names a rule writes with plain `name: value` declarations. */
+const writtenAttrs = (rule: Rule): Set<string> => {
+  const names = new Set<string>();
+  rule.attributes.forEach((prop) => {
+    if (prop instanceof StyleProperty) return;
+    if (NON_ATTRIBUTE_KEYS.has(prop.key)) return;
+    names.add(prop.key);
+  });
+  return names;
+};
+
+/** Strongly connected components with more than one rule (Tarjan). */
+const cycles = (rules: Rule[], edges: Map<Rule, Set<Rule>>): Rule[][] => {
+  let index = 0;
+  const indices = new Map<Rule, number>();
+  const lowlinks = new Map<Rule, number>();
+  const onStack = new Set<Rule>();
+  const stack: Rule[] = [];
+  const found: Rule[][] = [];
+  const connect = (rule: Rule) => {
+    indices.set(rule, index);
+    lowlinks.set(rule, index);
+    index++;
+    stack.push(rule);
+    onStack.add(rule);
+    edges.get(rule)?.forEach((next) => {
+      if (!indices.has(next)) {
+        connect(next);
+        lowlinks.set(rule, Math.min(lowlinks.get(rule)!, lowlinks.get(next)!));
+      } else if (onStack.has(next)) {
+        lowlinks.set(rule, Math.min(lowlinks.get(rule)!, indices.get(next)!));
+      }
+    });
+    if (lowlinks.get(rule) === indices.get(rule)) {
+      const component: Rule[] = [];
+      let member: Rule;
+      do {
+        member = stack.pop()!;
+        onStack.delete(member);
+        component.push(member);
+      } while (member !== rule);
+      if (component.length > 1) found.push(component.reverse());
+    }
+  };
+  rules.forEach((rule) => {
+    if (!indices.has(rule)) connect(rule);
+  });
+  return found;
+};
+
+/**
+ * Warn (once per sheet) when attr writes and selector gates form a
+ * cycle. Returns the cycles for tests / tooling.
+ */
+export const warnStaticCycles = (quark: Quark): Rule[][] => {
+  const rules = quark.rules.filter((rule) => !rule.isEventBlock);
+  if (rules.length < 2) return [];
+  const writes = new Map(rules.map((rule) => [rule, writtenAttrs(rule)]));
+  const edges = new Map<Rule, Set<Rule>>();
+  rules.forEach((from) => {
+    const written = writes.get(from)!;
+    if (!written.size) return;
+    rules.forEach((to) => {
+      if (to === from) return;
+      for (const name of written) {
+        if (to.observedAttrs.has(name)) {
+          let targets = edges.get(from);
+          if (!targets) edges.set(from, (targets = new Set()));
+          targets.add(to);
+          break;
+        }
+      }
+    });
+  });
+  if (!edges.size) return [];
+  const found = cycles(rules, edges);
+  found.forEach((component) => {
+    const members = new Set(component);
+    const description = component
+      .map((rule) => {
+        const shared = [...writes.get(rule)!].filter((name) =>
+          component.some(
+            (other) =>
+              other !== rule &&
+              members.has(other) &&
+              other.observedAttrs.has(name)
+          )
+        );
+        return `\`${rule.selector}\` writes [${shared.join(", ")}]`;
+      })
+      .join("; ");
+    QuarkLogger.warn({
+      method: "cycleCheck",
+      message: `Quark: rules gate on attributes they write for each other — ${description}. A cycle that never settles is cut by the loop guard after ${LoopGuard.limit} hops; make the writes converge or break the cycle.`,
+    });
+  });
+  return found;
+};

package/src/devtools-hook.ts

@@ -0,0 +1,303 @@
+import { evaluateExpression, getExpressionAst } from "./evaluator";
+import { type Quark, QuarkRegistry } from "./quark";
+import type { QuarkInternal, TQuarkElement } from "./quark-internal";
+import type { Rule } from "./rule";
+import { createScope } from "./variables";
+import {
+  type DevtoolsRenderer,
+  NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  registerRenderer,
+  toDevtoolsJson,
+} from "@excom/kit-devtools";
+
+/**
+ * Quark DevTools probe. Hook is in `@excom/kit-devtools`; this
+ * adds the Quark renderer and helpers.
+ *
+ *   publicize(["quark", "sheet", "registered"], { weakElement: host, sheetId, … })
+ *   publicize(["quark", "sheet", "unregistered"], { weakElement: host, sheetId })
+ *   publicize(["quark", "apply"], { weakElement, selector, key, expression, result, … })
+ *   publicize(["quark", "error"], { weakElement, selector, key, expression, errorMessage, … })
+ *
+ * `apply` is one property resolve (selector ≡ lifecycle, `{ key: result }`
+ * ≡ effect). Group a rule run by `runId`.
+ */
+export {
+  attachDevtools,
+  type DevtoolsHook,
+  getDevtoolsHook,
+  publicize,
+} from "@excom/kit-devtools";
+
+export type QuarkInspectSnapshot = {
+  tag: string;
+  id: string | null;
+  /** `$variable` bindings owned by this element. */
+  vars: Record<string, unknown>;
+  /** Attributes Quark has written on this element, with their current value. */
+  attributes: Record<string, string | null>;
+  /** CSS custom properties Quark has written on this element's inline style. */
+  styleProperties: Record<string, string | null>;
+  /**
+   * Listeners from Quark `@on` at-rules, per event type, one entry per
+   * attached function, tagged with the declaration that produced it
+   * (`$expression`, e.g. `setOutputFromDetail`).
+   */
+  listeners: Record<string, DevtoolsFunctionRef[]>;
+  /** `iterate()` row context, when this element is a rendered row. */
+  loop: { index: unknown; key: unknown } | null;
+  /** Sheet hashes that have touched this element. */
+  sheets: string[];
+};
+
+/** JSON-safe stand-in for a function, as rendered by DevTools. */
+export type DevtoolsFunctionRef = {
+  $constructor: "Function";
+  /** Quark declaration source that produced it, when known. */
+  $expression: string | null;
+};
+
+/** `@on <events> [(options)]` handle text of a registered rule, if found. */
+const listenerExpression = (
+  sheetHash: string,
+  ruleId: number,
+  slot: string
+): string | null => {
+  const rule = QuarkRegistry.findRules(ruleId).find(
+    (r) => r.quarkInstance.hash === sheetHash
+  );
+  const listener = rule?.listeners.find((l) => l.key === slot);
+  if (!listener) return null;
+  // `@on click (handle: a) { … }` → "a { … }"; a bare block shows as "{ … }"
+  return [listener.handleText, listener.block ? "{ … }" : ""]
+    .filter(Boolean)
+    .join(" ");
+};
+
+/** One declaration of a rule, as authored (`key: value`). */
+export type QuarkDeclarationInfo = {
+  key: string;
+  value: string;
+  /** The `@view-transition` block the write sits in (`@view-transition (types: "t")`). */
+  transition?: string;
+};
+
+/** One `@warn` / `@debug` / `@error` statement of a rule. */
+export type QuarkDiagnosticInfo = {
+  level: "warn" | "debug" | "error";
+  /** The statement's expression as authored. */
+  expression: string;
+};
+
+/** One `@delay` block of a rule. */
+export type QuarkDelayInfo = {
+  /** The duration expression as authored (`2000`, `$ms * 2`). */
+  duration: string;
+};
+
+/** One `@on` at-rule of a rule. */
+export type QuarkListenerInfo = {
+  /** Display key: `@on click`, `@on keydown (key: "Escape")`, `@on input, change (handle: save)`. */
+  key: string;
+  /** DOM event types the listener registers for. */
+  events: string[];
+  /** The `handle:` option as written, `""` when absent. */
+  handlers: string;
+  hasBlock: boolean;
+};
+
+/** A rule as the agent tooling sees it (no element references). */
+export type QuarkRuleInfo = {
+  sheetId: number;
+  ruleId: number;
+  /** Authored selector, nested rules expanded to their full line. */
+  selector: string;
+  isScoped: boolean;
+  numberOfRuns: number;
+  declarations: QuarkDeclarationInfo[];
+  listeners: QuarkListenerInfo[];
+  diagnostics: QuarkDiagnosticInfo[];
+  delays: QuarkDelayInfo[];
+};
+
+/** A registered sheet. `host` is live; callers serialize it themselves. */
+export type QuarkSheetInfo = {
+  sheetId: number;
+  hash: string;
+  host: Element | null;
+  scopeId: string | null;
+  isScoped: boolean;
+  isRegistered: boolean;
+  ruleCount: number;
+  src: string;
+  rules: QuarkRuleInfo[];
+};
+
+export type QuarkRenderer = DevtoolsRenderer & {
+  kind: "quark";
+  isQuarkElement: (el: Element) => boolean;
+  inspect: (el: Element) => QuarkInspectSnapshot | null;
+  /** Every registered sheet with its rules (agent tooling). */
+  sheets: () => QuarkSheetInfo[];
+  /**
+   * Rules whose selector matches `el` right now, in definition order
+   * across sheets (later wins on conflicting writes). Scope-aware.
+   */
+  matchingRules: (el: Element) => QuarkRuleInfo[];
+  /**
+   * Evaluate a Quark expression as if declared on a rule matching `el`
+   * (`$bindings`, `attr()`, `prop()`, `@use` modules of `sheetId` or of the
+   * first sheet touching the element). Returns the raw value; throws the
+   * evaluator's error. Read-only by the language's design, but a `@use`
+   * function may still side-effect.
+   */
+  evaluate: (el: Element, expression: string, sheetId?: number) => unknown;
+};
+
+const liveSheets = (): Quark[] =>
+  QuarkRegistry.sheets
+    .map((ref) => ref.deref())
+    .filter((sheet): sheet is Quark => !!sheet);
+
+const ruleInfo = (rule: Rule): QuarkRuleInfo => ({
+  sheetId: rule.quarkInstance.id,
+  ruleId: rule.id,
+  selector: rule.selector,
+  isScoped: rule.isScoped,
+  numberOfRuns: rule.numberOfRuns,
+  declarations: [...rule.variables, ...rule.attributes].map(
+    ({ key, value, transition }) => ({
+      key,
+      value,
+      ...(transition ? { transition: transition.source } : {}),
+    })
+  ),
+  listeners: rule.listeners.map((listener) => ({
+    key: listener.key,
+    events: listener.eventTypes,
+    handlers: listener.handleText,
+    hasBlock: !!listener.block,
+  })),
+  diagnostics: rule.diagnostics.map(({ level, value }) => ({
+    level,
+    expression: value,
+  })),
+  delays: rule.delays.map(({ value }) => ({ duration: value })),
+});
+
+const sheetInfo = (sheet: Quark): QuarkSheetInfo => ({
+  sheetId: sheet.id,
+  hash: sheet.hash,
+  host: sheet.host?.deref() ?? null,
+  scopeId: sheet.scopeId,
+  isScoped: !!sheet.options.isScoped,
+  isRegistered: sheet.isRegistered,
+  ruleCount: sheet.rules.length,
+  src: sheet.src,
+  rules: sheet.rules.map(ruleInfo),
+});
+
+const rulesMatching = (el: Element): Rule[] =>
+  liveSheets().flatMap((sheet) => {
+    const host = sheet.host?.deref();
+    if (!host || !sheet.isRegistered) return [];
+    return sheet.rules.filter((rule) => rule.matchesElement(el, host));
+  });
+
+const evaluateOn = (
+  el: Element,
+  expression: string,
+  sheetId?: number
+): unknown => {
+  // module scope comes from a rule's sheet; pick the requested sheet, else
+  // the first one whose rules match the element, else any registered sheet
+  const sheets = liveSheets();
+  const sheet =
+    sheetId !== undefined
+      ? sheets.find((s) => s.id === sheetId)
+      : (rulesMatching(el)[0]?.quarkInstance ?? sheets[0]);
+  const rule = sheet?.rules[0];
+  const scope = createScope({
+    element: el as HTMLElement,
+    options: rule ? { rule } : {},
+  });
+  return evaluateExpression(getExpressionAst(expression), {
+    scope,
+    element: el,
+  });
+};
+
+const inspectInternal = (
+  el: Element,
+  internal: QuarkInternal
+): QuarkInspectSnapshot => {
+  const vars: Record<string, unknown> = {};
+  for (const name of Object.keys(internal.vars)) {
+    try {
+      vars[name] = toDevtoolsJson(internal.getVar(name));
+    } catch {
+      vars[name] = "[unreadable]";
+    }
+  }
+  const attributes: Record<string, string | null> = {};
+  const styleProperties: Record<string, string | null> = {};
+  const listeners: Record<string, DevtoolsFunctionRef[]> = {};
+  const style = (el as HTMLElement).style;
+  for (const [sheetHash, instance] of Object.entries(internal.instances)) {
+    for (const name of Object.keys(instance.attributes)) {
+      if (name === "content") continue;
+      if (name.startsWith("--")) {
+        const value = style?.getPropertyValue(name);
+        styleProperties[name] = value ? value : null;
+      } else {
+        attributes[name] = el.getAttribute(name);
+      }
+    }
+    for (const [ruleId, rule] of Object.entries(instance.rules)) {
+      for (const [slot, fns] of Object.entries(rule.listeners)) {
+        const attached = fns.filter(Boolean);
+        if (!attached.length) continue;
+        const $expression = listenerExpression(sheetHash, Number(ruleId), slot);
+        // keyed by events plus options: `click`, `keydown (key: "Escape")`, `input, change (debounce: 300)`
+        const eventType = slot.replace(/^@on /, "");
+        listeners[eventType] = [
+          ...(listeners[eventType] ?? []),
+          ...attached.map(() => ({
+            $constructor: "Function" as const,
+            $expression,
+          })),
+        ];
+      }
+    }
+  }
+  const { index, key } = internal.loop;
+  return {
+    tag: el.localName,
+    id: el.id || null,
+    vars,
+    attributes,
+    styleProperties,
+    listeners,
+    loop:
+      index !== undefined || key !== undefined
+        ? { index: index ?? null, key: toDevtoolsJson(key ?? null) }
+        : null,
+    sheets: Object.keys(internal.instances),
+  };
+};
+
+const renderer: QuarkRenderer = {
+  version: NUCLEUS_DEVTOOLS_HOOK_VERSION,
+  kind: "quark",
+  isQuarkElement: (el) => !!(el as TQuarkElement)?._q_,
+  inspect: (el) => {
+    const internal = (el as TQuarkElement)?._q_;
+    if (!internal) return null;
+    return inspectInternal(el, internal);
+  },
+  sheets: () => liveSheets().map(sheetInfo),
+  matchingRules: (el) => rulesMatching(el).map(ruleInfo),
+  evaluate: evaluateOn,
+};
+
+registerRenderer(renderer);

package/src/element-api.ts

@@ -0,0 +1,109 @@
+/**
+ * `element.quark`: the JS side of `$variable` bindings, shaped like
+ * `element.style` (`setProperty` / `removeProperty` / `getPropertyValue`).
+ *
+ * The element you call it on becomes the binding's owner, exactly as a
+ * rule declaring `$name` there would: descendants (in any sheet) resolve
+ * it by walking up, a nearer owner shadows it, and a real change fires
+ * the bubbling `quark-binding-change` that re-runs readers. It works on
+ * elements no rule has matched — that is the owner case. Writes carry
+ * `sheetId: null` so DevTools can tell a JS write from a rule's.
+ *
+ * Change detection is by value (`hashObject` for objects): pass a new
+ * object, an in-place mutation is invisible — same as a rule. Primitives
+ * that should be selectable belong in attributes (`setAttribute` +
+ * `attr()`); this API earns its place for rich values and for `$name`
+ * reads in a subtree. One writer per name per element: a rule that
+ * declares `$name` on the same element rewrites a JS value when its def
+ * re-runs (last writer wins; revisited with specificity / priority).
+ */
+import {
+  type BindingChangeDetail,
+  dispatchBindingChange,
+  readBinding,
+  writeBinding,
+} from "./bindings";
+import { SYMBOL_UNSET } from "./constants";
+
+/** `count` and `$count` both name the `$count` binding. */
+const bindingName = (name: string): string =>
+  name.startsWith("$") ? name : `$${name}`;
+
+const JS_WRITE: Omit<BindingChangeDetail, "name"> = { sheetId: null };
+
+export class QuarkElementApi {
+  private readonly element: Element;
+  constructor(element: Element) {
+    this.element = element;
+  }
+  /**
+   * Write a binding on this element. Returns `true` when the stored value
+   * changed (readers re-run synchronously before it returns).
+   */
+  setProperty(name: string, value: unknown): boolean {
+    return writeBinding(this.element, bindingName(name), value, JS_WRITE);
+  }
+  /**
+   * Write several bindings, announcing them after all are stored, so a
+   * reader of two names sees both new values on its one re-run.
+   */
+  setProperties(values: Record<string, unknown>): boolean {
+    const pending: BindingChangeDetail[] = [];
+    let changed = false;
+    for (const [name, value] of Object.entries(values)) {
+      changed =
+        writeBinding(
+          this.element,
+          bindingName(name),
+          value,
+          JS_WRITE,
+          (_owner, detail) => {
+            pending.push(detail);
+          }
+        ) || changed;
+    }
+    pending.forEach((detail) => dispatchBindingChange(this.element, detail));
+    return changed;
+  }
+  /** `unset`: delete the binding so descendants fall through to an ancestor. */
+  removeProperty(name: string): boolean {
+    return writeBinding(
+      this.element,
+      bindingName(name),
+      SYMBOL_UNSET,
+      JS_WRITE
+    );
+  }
+  /** The value a rule on this element would read (nearest owner, self first). */
+  getPropertyValue(name: string): unknown {
+    return readBinding(this.element, bindingName(name));
+  }
+}
+
+declare global {
+  interface Element {
+    /** Quark bindings on this element, see `QuarkElementApi`. */
+    readonly quark: QuarkElementApi;
+  }
+}
+
+const handles = new WeakMap<Element, QuarkElementApi>();
+
+/**
+ * Define the lazy `quark` accessor on `Element.prototype` (SVG nodes can
+ * own bindings too). Idempotent; `configurable` so tests can remove it.
+ */
+export const installElementApi = (
+  proto: object = typeof Element === "undefined" ? {} : Element.prototype
+): void => {
+  if (Object.getOwnPropertyDescriptor(proto, "quark")) return;
+  Object.defineProperty(proto, "quark", {
+    configurable: true,
+    enumerable: false,
+    get(this: Element): QuarkElementApi {
+      let handle = handles.get(this);
+      if (!handle) handles.set(this, (handle = new QuarkElementApi(this)));
+      return handle;
+    },
+  });
+};