@nxisai/nxis 2.1.2 → 2.2.2

package/src/webmcp/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @packageDocumentation
+ *
+ * `nxis/webmcp` — WebMCP tool registration for NxisAI structured data.
+ *
+ * @remarks
+ * This subpath export reads Action + EntryPoint JSON-LD injected by the
+ * NxisAI backend and registers each Action as a WebMCP tool via
+ * `document.modelContext.registerTool`. Each tool's `execute` locates the
+ * real `<form>` on the live page and fills it.
+ *
+ * **Browser-only.** This module requires `document.modelContext` (Chrome 149+).
+ * It gracefully no-ops in environments where WebMCP is unavailable.
+ *
+ * @example
+ * ```typescript
+ * import { registerActions } from 'nxis/webmcp';
+ *
+ * // Auto-register all Action tools found in the page's JSON-LD
+ * const cleanup = registerActions();
+ *
+ * // Later, to unregister all tools:
+ * cleanup();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Opt-out of MutationObserver re-scan for SPAs
+ * const cleanup = registerActions({ observe: false });
+ * ```
+ */
+
+export { registerActions } from './register';
+export type { RegisterOptions } from './register';
+
+// Re-export contract types for consumers who need them
+export type {
+  NxisAction,
+  NxisEntryPoint,
+  NxisPropertyValueSpecification,
+  NxisValueOption,
+  NxisValueType,
+  ActionSubtype,
+} from './contract';
+export { isActionType, ACTION_SUBTYPES } from './contract';
+
+// Re-export parse for advanced usage
+export { readActions } from './parse';
+
+// Re-export schema for testing / advanced usage
+export { buildInputSchema } from './schema';

package/src/webmcp/locate.ts

@@ -0,0 +1,200 @@
+/**
+ * Form locator — heuristically locates the real `<form>` element
+ * corresponding to a NxisAction.
+ *
+ * Three-step cascade:
+ *   1. Target-based candidate collection (URL match or all forms for endpointless)
+ *   2. Field-set containment disambiguation (superset of valueName set)
+ *   3. Endpointless degenerate case (smallest superset wins)
+ *
+ * @internal
+ */
+
+import { NxisAction } from './contract';
+
+/**
+ * Locate the form element on the live page that corresponds to the given Action.
+ *
+ * @param action - The parsed NxisAction to locate a form for.
+ * @returns The matching HTMLFormElement, or null if no unambiguous match found.
+ */
+export function locateForm(action: NxisAction): HTMLFormElement | null {
+  const allForms = Array.from(document.querySelectorAll('form'));
+  if (allForms.length === 0) return null;
+
+  const actionValueNames = getActionValueNames(action);
+  const isEndpointless = !action.target.urlTemplate;
+
+  // Step 1: Target-based candidate collection
+  let candidates: HTMLFormElement[];
+
+  if (isEndpointless) {
+    // SelfPage / ClientSide — all forms are candidates (URL is uninformative)
+    candidates = allForms;
+  } else {
+    // URL target — filter by resolved action URL + method
+    candidates = filterByUrlAndMethod(
+      allForms,
+      action.target.urlTemplate!,
+      action.target.httpMethod
+    );
+  }
+
+  if (candidates.length === 0) {
+    // Fallback: try all forms if URL match yielded nothing
+    candidates = allForms;
+  }
+
+  if (candidates.length === 1) {
+    return candidates[0];
+  }
+
+  // Step 2: Field-set containment disambiguation
+  // Keep forms whose control names are a superset of the Action's valueNames
+  const fieldMatches = candidates
+    .map(form => ({
+      form,
+      controlNames: getFormControlNames(form),
+    }))
+    .filter(({ controlNames }) =>
+      actionValueNames.every(name => controlNames.has(name))
+    );
+
+  if (fieldMatches.length === 0) {
+    // No field-set match — fall back to first URL/method candidate
+    console.warn(
+      `[nxis/webmcp] No field-set match for action "${action.name}". ` +
+      `Expected fields: [${actionValueNames.join(', ')}]. ` +
+      `Falling back to first candidate.`
+    );
+    return candidates[0];
+  }
+
+  if (fieldMatches.length === 1) {
+    return fieldMatches[0].form;
+  }
+
+  // Step 3: Multiple field-set matches — pick smallest superset (closest match)
+  fieldMatches.sort((a, b) => a.controlNames.size - b.controlNames.size);
+
+  // If the two smallest are the same size, it's truly ambiguous
+  if (fieldMatches[0].controlNames.size === fieldMatches[1].controlNames.size) {
+    console.warn(
+      `[nxis/webmcp] Ambiguous form match for action "${action.name}". ` +
+      `${fieldMatches.length} forms have identical field sets. Returning null.`
+    );
+    return null;
+  }
+
+  return fieldMatches[0].form;
+}
+
+/**
+ * Extract the set of valueName keys from an Action's input specs.
+ */
+function getActionValueNames(action: NxisAction): string[] {
+  if (!action.input) return [];
+  return action.input.map(pvs => pvs.valueName);
+}
+
+/**
+ * Get the set of control `name` attributes from a form.
+ */
+function getFormControlNames(form: HTMLFormElement): Set<string> {
+  const names = new Set<string>();
+  const elements = form.elements;
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i] as HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+    if (el.name) {
+      names.add(el.name);
+    }
+  }
+  return names;
+}
+
+/**
+ * Filter forms by resolved action URL + method match.
+ */
+function filterByUrlAndMethod(
+  forms: HTMLFormElement[],
+  urlTemplate: string,
+  httpMethod: string
+): HTMLFormElement[] {
+  const target = resolveTemplateUrl(urlTemplate);
+
+  return forms.filter(form => {
+    // Method match (case-insensitive)
+    const formMethod = (form.method || 'GET').toUpperCase();
+    if (formMethod !== httpMethod.toUpperCase()) return false;
+
+    // If the template can't be resolved to an absolute URL, don't exclude on
+    // URL — let field-set disambiguation decide.
+    if (!target) return true;
+
+    const formAction = resolveFormAction(form);
+    return urlsMatch(formAction, target);
+  });
+}
+
+/**
+ * Resolve an Action's urlTemplate to an absolute URL, dropping RFC 6570
+ * template vars (e.g. `?q={query}`) first. Returns null if unparseable.
+ */
+function resolveTemplateUrl(urlTemplate: string): URL | null {
+  const stripped = urlTemplate.replace(/\{[^}]*\}/g, '');
+  try {
+    return new URL(stripped, window.location.href);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Match a form's resolved action URL against the Action's target URL.
+ *
+ * Requires the same origin, then compares paths on segment boundaries (the
+ * target path may be a prefix once trailing template vars are stripped). The
+ * query string is ignored — it carries the template's input values, not identity.
+ */
+function urlsMatch(formActionHref: string, target: URL): boolean {
+  let formUrl: URL;
+  try {
+    formUrl = new URL(formActionHref, window.location.href);
+  } catch {
+    return false;
+  }
+
+  if (formUrl.origin !== target.origin) return false;
+
+  const formPath = formUrl.pathname.replace(/\/+$/, '');
+  const targetPath = target.pathname.replace(/\/+$/, '');
+
+  // Empty target path (template was origin-only) → any path on this origin.
+  if (targetPath === '') return true;
+
+  return (
+    formPath === targetPath ||
+    formPath.startsWith(targetPath + '/') ||
+    targetPath.startsWith(formPath + '/')
+  );
+}
+
+/**
+ * Resolve a form's action attribute to an absolute URL.
+ * Forms with no action, empty action, or `#` resolve to the current page.
+ */
+function resolveFormAction(form: HTMLFormElement): string {
+  const raw = form.getAttribute('action');
+  if (!raw || raw === '#' || raw.startsWith('#') || raw === '') {
+    return window.location.href.split('#')[0].split('?')[0];
+  }
+  if (raw.startsWith('javascript:')) {
+    return window.location.href.split('#')[0].split('?')[0];
+  }
+
+  try {
+    return new URL(raw, window.location.href).href;
+  } catch {
+    return raw;
+  }
+}

package/src/webmcp/parse.ts

@@ -0,0 +1,276 @@
+/**
+ * JSON-LD parser — reads Action specs from the page's structured data.
+ *
+ * Selects all `<script type="application/ld+json">` blocks, parses them,
+ * flattens `@graph` containers, and collects Action nodes.
+ *
+ * Total parsing: every step fails soft — malformed blocks are skipped,
+ * never fatal. A page may have dozens of JSON-LD blocks; we only collect
+ * the ones that are valid Action nodes.
+ *
+ * @internal
+ */
+
+import { NxisAction, NxisEntryPoint, NxisPropertyValueSpecification, isActionType } from './contract';
+
+/** The NxisAI namespace IRI — used for expanded property lookups. */
+const NXIS_NS = 'https://nxis.ai/ns#';
+
+/**
+ * Resolve a property value from an object, trying the compact nxis: prefix
+ * first, then the fully expanded IRI. JSON-LD processors may store properties
+ * under either form depending on whether @context was applied.
+ */
+function resolveValue(obj: Record<string, unknown>, compact: string, expanded: string): unknown {
+  return obj[compact] ?? obj[expanded];
+}
+
+/**
+ * Resolve an array property, trying compact then expanded key.
+ */
+function resolveArray(obj: Record<string, unknown>, compact: string, expanded: string): unknown[] {
+  const val = resolveValue(obj, compact, expanded);
+  return Array.isArray(val) ? val : [];
+}
+
+/**
+ * Read all Action specs from JSON-LD blocks in the document.
+ *
+ * @param doc - The document to scan. Defaults to `document`.
+ * @returns Array of parsed NxisAction objects. Never throws.
+ */
+export function readActions(
+  doc: Document | undefined = typeof document !== 'undefined' ? document : undefined
+): NxisAction[] {
+  const actions: NxisAction[] = [];
+
+  // Browser-only — no DOM means no JSON-LD to read.
+  if (!doc) return actions;
+
+  const scripts = doc.querySelectorAll('script[type="application/ld+json"]');
+  for (const script of Array.from(scripts)) {
+    const text = script.textContent;
+    if (!text) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      // Malformed JSON — skip, not fatal
+      continue;
+    }
+
+    // Flatten @graph containers and collect Action nodes
+    const nodes = flattenGraph(parsed);
+    for (const node of nodes) {
+      const action = parseActionNode(node);
+      if (action) {
+        actions.push(action);
+      }
+    }
+  }
+
+  return actions;
+}
+
+/**
+ * Flatten a parsed JSON-LD value into individual nodes.
+ * Handles top-level arrays, `@graph` containers, and single objects.
+ */
+function flattenGraph(parsed: unknown): unknown[] {
+  if (Array.isArray(parsed)) {
+    // Could be an array of nodes or an array containing @graph objects
+    const results: unknown[] = [];
+    for (const item of parsed) {
+      results.push(...flattenGraph(item));
+    }
+    return results;
+  }
+
+  if (parsed && typeof parsed === 'object') {
+    const obj = parsed as Record<string, unknown>;
+    // Check for @graph container
+    if (Array.isArray(obj['@graph'])) {
+      const results: unknown[] = [];
+      for (const item of obj['@graph']) {
+        results.push(...flattenGraph(item));
+      }
+      return results;
+    }
+    // Single object node
+    return [obj];
+  }
+
+  return [];
+}
+
+/**
+ * Attempt to parse a raw JSON node as a NxisAction.
+ * Returns null if the node is not a valid Action.
+ */
+function parseActionNode(node: unknown): NxisAction | null {
+  if (!node || typeof node !== 'object') return null;
+
+  const obj = node as Record<string, unknown>;
+
+  // Check @type — must end with "Action" or be a known subtype
+  const type = typeof obj['@type'] === 'string' ? obj['@type'] : null;
+  if (!type) return null;
+  if (!type.endsWith('Action') && !isActionType(type)) return null;
+
+  // Required fields
+  const id = typeof obj['@id'] === 'string' ? obj['@id'] : null;
+  const name = typeof obj['name'] === 'string' ? obj['name'] : null;
+  const target = parseEntryPoint(obj['target']);
+
+  if (!id || !name || !target) return null;
+
+  // Parse input PVS array — check both compact (nxis:input) and expanded IRI forms.
+  // The backend emits "nxis:input" (not bare "input") because schema.org has no
+  // input property on Action — using bare "input" would expand to the invalid
+  // https://schema.org/input under @context of https://schema.org/.
+  const rawInput = resolveArray(obj, 'nxis:input', NXIS_NS + 'input');
+  const input = rawInput
+    .map(parsePVS)
+    .filter((pvs): pvs is NxisPropertyValueSpecification => pvs !== null);
+
+  const description = typeof obj['description'] === 'string'
+    ? obj['description']
+    : generateFallbackDescription(type, name, input);
+
+  return {
+    '@context': obj['@context'],
+    '@type': type,
+    '@id': id,
+    name,
+    description,
+    target,
+    input: input.length > 0 ? input : undefined,
+    'nxis:extractedAt': (
+      resolveValue(obj, 'nxis:extractedAt', NXIS_NS + 'extractedAt') as string | undefined
+    ),
+  };
+}
+
+/**
+ * Parse a raw object as a NxisEntryPoint.
+ * Returns null if required fields are missing.
+ */
+function parseEntryPoint(raw: unknown): NxisEntryPoint | null {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const obj = raw as Record<string, unknown>;
+
+  const httpMethod = typeof obj['httpMethod'] === 'string'
+    ? obj['httpMethod'].toUpperCase()
+    : null;
+  if (!httpMethod) return null;
+
+  const entryPoint: NxisEntryPoint = {
+    '@type': 'EntryPoint',
+    httpMethod,
+  };
+
+  // Optional fields
+  if (typeof obj['encodingType'] === 'string') {
+    entryPoint.encodingType = obj['encodingType'];
+  }
+
+  // URL target
+  if (typeof obj['urlTemplate'] === 'string') {
+    entryPoint.urlTemplate = obj['urlTemplate'];
+  }
+
+  // Endpointless target — try both compact and expanded forms
+  const targetKind = resolveValue(obj, 'nxis:targetKind', NXIS_NS + 'targetKind');
+  if (targetKind === 'selfPage' || targetKind === 'clientSide') {
+    entryPoint['nxis:targetKind'] = targetKind;
+  }
+  const pageUrl = resolveValue(obj, 'nxis:pageUrl', NXIS_NS + 'pageUrl');
+  if (typeof pageUrl === 'string') {
+    entryPoint['nxis:pageUrl'] = pageUrl;
+  }
+  const jsHandled = resolveValue(obj, 'nxis:jsHandled', NXIS_NS + 'jsHandled');
+  if (jsHandled === true) {
+    entryPoint['nxis:jsHandled'] = true;
+  }
+
+  return entryPoint;
+}
+
+/**
+ * Parse a raw object as a NxisPropertyValueSpecification.
+ * Returns null if `valueName` is missing (no property key = no tool parameter).
+ */
+function parsePVS(raw: unknown): NxisPropertyValueSpecification | null {
+  if (!raw || typeof raw !== 'object') return null;
+
+  const obj = raw as Record<string, unknown>;
+
+  const valueName = typeof obj['valueName'] === 'string' ? obj['valueName'] : null;
+  if (!valueName) return null;
+
+  const valueType = resolveValue(obj, 'nxis:valueType', NXIS_NS + 'valueType');
+  const vtStr = typeof valueType === 'string'
+    ? valueType as NxisPropertyValueSpecification['nxis:valueType']
+    : 'string'; // default to string if missing
+
+  const pvs: NxisPropertyValueSpecification = {
+    '@type': 'PropertyValueSpecification',
+    valueName,
+    'nxis:valueType': vtStr,
+  };
+
+  // Optional fields — only set if present and correct type
+  if (typeof obj['description'] === 'string') pvs.description = obj['description'];
+  if (obj['valueRequired'] === true) pvs.valueRequired = true;
+  if (typeof obj['defaultValue'] === 'string') pvs.defaultValue = obj['defaultValue'];
+  if (typeof obj['valueMinLength'] === 'number') pvs.valueMinLength = obj['valueMinLength'];
+  if (typeof obj['valueMaxLength'] === 'number') pvs.valueMaxLength = obj['valueMaxLength'];
+  if (typeof obj['minValue'] === 'number') pvs.minValue = obj['minValue'];
+  if (typeof obj['maxValue'] === 'number') pvs.maxValue = obj['maxValue'];
+  if (typeof obj['stepValue'] === 'number') pvs.stepValue = obj['stepValue'];
+  if (typeof obj['valuePattern'] === 'string') pvs.valuePattern = obj['valuePattern'];
+  if (obj['multipleValues'] === true) pvs.multipleValues = true;
+  if (obj['readonlyValue'] === true) pvs.readonlyValue = true;
+
+  // Parse options array — try both compact and expanded forms
+  const rawOptions = resolveArray(obj, 'nxis:valueOption', NXIS_NS + 'valueOption');
+  if (rawOptions.length > 0) {
+    const options = rawOptions
+      .filter((o: unknown) => o && typeof o === 'object' && typeof (o as Record<string, unknown>)['value'] === 'string')
+      .map((o: unknown) => {
+        const opt = o as Record<string, unknown>;
+        return {
+          '@type': 'nxis:ValueOption' as const,
+          value: opt['value'] as string,
+          name: typeof opt['name'] === 'string' ? opt['name'] : undefined,
+        };
+      });
+    if (options.length > 0) {
+      pvs['nxis:valueOption'] = options;
+    }
+  }
+
+  return pvs;
+}
+
+/**
+ * Generate a human-readable fallback description from the action metadata.
+ * Chrome best practices: "Describe what the tool does and when to use it."
+ */
+function generateFallbackDescription(
+  type: string,
+  name: string,
+  input: NxisPropertyValueSpecification[]
+): string {
+  // "CommunicateAction" → "communicate"
+  const verb = type.replace(/Action$/, '').toLowerCase();
+  const fieldList = input.map(f => f.valueName).join(', ');
+
+  if (input.length === 0) {
+    return `Trigger the ${verb} action "${name}".`;
+  }
+
+  return `Fill the ${verb} form "${name}" with fields: ${fieldList}.`;
+}

package/src/webmcp/reconcile.ts

@@ -0,0 +1,170 @@
+/**
+ * DOM reconciliation — cross-checks the Action's claimed descriptors
+ * against the resolved form's real controls.
+ *
+ * The live DOM is authoritative. Where the JSON-LD and the form's
+ * real controls conflict, we trust the DOM.
+ *
+ * @internal
+ */
+
+import { NxisAction, NxisPropertyValueSpecification } from './contract';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Fill strategy for a single reconciled field. */
+export type FillStrategy =
+  | { kind: 'value'; element: HTMLInputElement | HTMLTextAreaElement }
+  | { kind: 'checked'; element: HTMLInputElement }
+  | { kind: 'radio'; name: string; elements: HTMLInputElement[] }
+  | { kind: 'checkboxGroup'; name: string; elements: HTMLInputElement[] }
+  | { kind: 'select'; element: HTMLSelectElement; allowedValues: string[] }
+  | { kind: 'multiSelect'; element: HTMLSelectElement; allowedValues: string[] }
+  | { kind: 'skip'; reason: string };
+
+/** A reconciled field — pairs a valueName to its real element + fill strategy. */
+export interface ReconciledField {
+  valueName: string;
+  pvs: NxisPropertyValueSpecification;
+  strategy: FillStrategy;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile the Action's claimed field descriptors against the form's real controls.
+ *
+ * Rules (from implementation plan):
+ *   - valueName with no matching control → skip (don't fail the whole fill)
+ *   - Real control type contradicts claimed valueType → follow the DOM
+ *   - Real control is <select> → constrain to its actual <option>s
+ *   - readonlyValue mismatch → trust DOM readonly attribute
+ *
+ * @param action - The parsed Action with claimed descriptors.
+ * @param form - The located form element.
+ * @returns Array of ReconciledField objects.
+ */
+export function reconcileFields(
+  action: NxisAction,
+  form: HTMLFormElement
+): ReconciledField[] {
+  const specs = action.input ?? [];
+  return specs.map(pvs => reconcileField(pvs, form));
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function reconcileField(
+  pvs: NxisPropertyValueSpecification,
+  form: HTMLFormElement
+): ReconciledField {
+  const make = (strategy: FillStrategy): ReconciledField => ({
+    valueName: pvs.valueName,
+    pvs,
+    strategy,
+  });
+
+  // Find every control sharing this name. Radio groups and checkbox groups
+  // legitimately have multiple controls under one name — taking only the
+  // first would mishandle them.
+  const named = getNamedControls(form, pvs.valueName);
+  const control = named[0] ?? null;
+
+  if (!control) {
+    return make({ kind: 'skip', reason: `No control found with name="${pvs.valueName}"` });
+  }
+
+  // Radio group — select the option whose value matches; collect the whole
+  // group so the executor can pick the right member. Disabled radios drop out.
+  if (control instanceof HTMLInputElement && control.type === 'radio') {
+    const elements = named.filter(
+      (el): el is HTMLInputElement =>
+        el instanceof HTMLInputElement && el.type === 'radio' && !el.disabled
+    );
+    if (elements.length === 0) {
+      return make({ kind: 'skip', reason: `Radio group "${pvs.valueName}" has no enabled options` });
+    }
+    return make({ kind: 'radio', name: pvs.valueName, elements });
+  }
+
+  // Checkbox — a lone checkbox is a boolean toggle; several sharing a name
+  // form a multi-select group where the value(s) pick which boxes to check.
+  if (control instanceof HTMLInputElement && control.type === 'checkbox') {
+    const elements = named.filter(
+      (el): el is HTMLInputElement =>
+        el instanceof HTMLInputElement && el.type === 'checkbox' && !el.disabled
+    );
+    if (elements.length === 0) {
+      return make({ kind: 'skip', reason: `Checkbox "${pvs.valueName}" is disabled` });
+    }
+    if (elements.length > 1) {
+      return make({ kind: 'checkboxGroup', name: pvs.valueName, elements });
+    }
+    return make({ kind: 'checked', element: elements[0] });
+  }
+
+  // Check if the real control is readonly (trust DOM over claimed)
+  const isReadonly = (control as HTMLInputElement).readOnly === true
+    || control.getAttribute('readonly') !== null;
+
+  if (isReadonly) {
+    return make({ kind: 'skip', reason: `Control "${pvs.valueName}" is readonly in the DOM` });
+  }
+
+  // Disabled controls cannot be filled
+  if ((control as HTMLInputElement).disabled) {
+    return make({ kind: 'skip', reason: `Control "${pvs.valueName}" is disabled` });
+  }
+
+  // Select element — constrain to actual <option> values
+  if (control instanceof HTMLSelectElement) {
+    const allowedValues: string[] = [];
+    for (let i = 0; i < control.options.length; i++) {
+      const opt = control.options[i];
+      if (opt.value) {
+        allowedValues.push(opt.value);
+      }
+    }
+    // <select multiple> accepts an array of values; a plain select takes one.
+    return make(
+      control.multiple
+        ? { kind: 'multiSelect', element: control, allowedValues }
+        : { kind: 'select', element: control, allowedValues }
+    );
+  }
+
+  // Textarea
+  if (control instanceof HTMLTextAreaElement) {
+    return make({ kind: 'value', element: control });
+  }
+
+  // Standard input — use value strategy
+  if (control instanceof HTMLInputElement) {
+    return make({ kind: 'value', element: control });
+  }
+
+  // Unknown element type
+  return make({ kind: 'skip', reason: `Unsupported control type for "${pvs.valueName}"` });
+}
+
+/**
+ * Collect every form control that shares the given `name`. Form controls of
+ * the same name (radio/checkbox groups) all participate in the same field.
+ */
+function getNamedControls(form: HTMLFormElement, name: string): Element[] {
+  const out: Element[] = [];
+  const elements = form.elements;
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i] as HTMLInputElement;
+    if (el.name === name) {
+      out.push(el);
+    }
+  }
+  return out;
+}