@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/base/eval.ts

@@ -0,0 +1,208 @@
+import { parse, evaluate as expEval, OnMissing } from "./expressionEval";
+import moment from "moment";
+import { v4 as uuidv4, v7 as uuidv7 } from "uuid";
+import jsep from "jsep";
+import { AppImpl, AppInstance, InstanceId } from "hkp-frontend/src/types";
+import { vaultGet, vaultSet } from "hkp-frontend/src/vault";
+
+export type Expression = jsep.Expression;
+
+function reformatDate(date: string, inputFormat: string, outputFormat: string) {
+  return moment(date, inputFormat).format(outputFormat);
+}
+
+export type SyntaxError = "syntax-error";
+
+export function parseExpression(f: string): Expression | SyntaxError {
+  try {
+    return parse(f);
+  } catch (err) {
+    console.error("parseExpression", err);
+    return "syntax-error";
+  }
+}
+
+export function fromVault(globalId: string) {
+  return vaultGet(globalId);
+}
+
+export function toVault(globalId: string, value: string) {
+  vaultSet(globalId, value);
+}
+
+const globalScope = {
+  print: console.log,
+  log: console.log,
+  round: Math.round,
+  sin: Math.sin,
+  min: Math.min,
+  max: Math.max,
+  rand: Math.random,
+  number: (x: string | number) => Number(x),
+  string: (x: number | string) => `${x}`,
+  stringify: JSON.stringify,
+  parse: (x: string | undefined) =>
+    x !== undefined ? JSON.parse(x) : "<parse undefined>",
+  concat: (...args: string[]) => args.join(""),
+  // An array's elements as one text, e.g. join(params.items, ''). An empty
+  // element is nothing, as Array.join has it.
+  join: (arr: unknown, separator?: string) =>
+    Array.isArray(arr)
+      ? arr.join(separator ?? "")
+      : arr === null || arr === undefined
+        ? ""
+        : `${arr}`,
+  reformatDate,
+  // Current date/time as a formatted string (moment format tokens), e.g.
+  // formatNow('dddd, MMMM, D. YYYY HH:mm') -> "Friday, July, 17. 2026 21:13"
+  formatNow: (format: string) => moment().format(format),
+  // Array search with an expression-string predicate — jsep has no lambdas,
+  // so the element is bound as `item` (and its position as `index`) inside
+  // the predicate, e.g. find(params.departures, 'isFuture(item.when)').
+  find: (arr: Array<any>, predicate: string) =>
+    Array.isArray(arr) ? arr.find(itemPredicate(predicate)) : undefined,
+  filter: (arr: Array<any>, predicate: string) =>
+    Array.isArray(arr) ? arr.filter(itemPredicate(predicate)) : [],
+  // Timestamp checks for anything Date can parse (ISO strings, epoch ms).
+  isFuture: (ts: string | number | null | undefined) =>
+    ts != null && new Date(ts).getTime() >= Date.now(),
+  isPast: (ts: string | number | null | undefined) =>
+    ts != null && new Date(ts).getTime() < Date.now(),
+  encodeURI,
+  blobToUint8Array: async (x: Blob) => new Uint8Array(await x.arrayBuffer()),
+  slice: (arr: Array<any>, offset: number, step: number, end: number) =>
+    arr.slice(offset, end).filter((_, i) => i % step === 0),
+  sum: (x: Array<number>) =>
+    x && x.reduce ? x.reduce((acc, v) => acc + v, 0) : x,
+  flatSum: (x: Array<any>) =>
+    x && x.flat ? x.flat().reduce((acc: number, v: number) => acc + v, 0) : 0,
+  at: (arr: Array<any>, i: number) => arr[Math.abs(Math.round(i)) % arr.length],
+  now: () => Date.now(),
+  range: (n: number) =>
+    Array.from({ length: Math.max(0, Math.round(n)) }, (_, i) => i),
+  avg: (x: Array<number>) =>
+    x && x.reduce ? x.reduce((acc, v) => acc + v, 0) / x.length : x,
+  arrayToAudioBuffer: (arr: Array<number>) => {
+    const audioCtx = new AudioContext();
+    const buffer = audioCtx.createBuffer(1, arr.length, audioCtx.sampleRate);
+    const channel = buffer.getChannelData(0);
+    arr.forEach((x, i) => (channel[i] = x));
+    return buffer;
+  },
+  fromQueryParam: (name: string) => {
+    const qp = new URLSearchParams(window.location.search);
+    return qp.get(name);
+  },
+  fromStorage: (name: string) => localStorage.getItem(name),
+  // Lowercases and strips everything outside [a-z0-9_-], turning free-form
+  // text into a canonical identifier — e.g. building a topic for a
+  // case-sensitive ntfy fetch URL.
+  slug: (x: string | number) =>
+    String(x)
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, ""),
+  // Text with the web addresses taken out, and with whatever label introduced
+  // one — "Article URL:" says less than nothing once the address is gone. For
+  // text on its way to something that speaks or summarises it, where an address
+  // is a minute of punctuation; never for what a board stores or publishes,
+  // where the address is the useful part.
+  withoutUrls: (x: unknown) =>
+    String(x ?? "")
+      .replace(/(?:[A-Za-z][\w ]{0,30}:[ \t]*)?(?:https?:\/\/|www\.)\S+/gi, " ")
+      .replace(/[ \t]{2,}/g, " ")
+      .replace(/\s+([.,;:!?])/g, "$1")
+      .trim(),
+  uuid: {
+    v4: uuidv4,
+    v7: uuidv7,
+  },
+  fromVault,
+  toVault,
+  moment,
+};
+
+// Compiles an expression-string predicate for find/filter. The predicate is
+// parsed once per call site and evaluated synchronously per element with
+// `item`/`index` in scope alongside the global helpers.
+function itemPredicate(predicate: string) {
+  const ast = parse(predicate);
+  return (item: any, index: number) =>
+    !!expEval(ast as any, { item, index, ...globalScope });
+}
+
+export const globalScopeFunctions = Object.keys({
+  ...globalScope,
+  ...{
+    getServiceConfig: "", // TODO: this will be added when running with an app
+    processRuntime: "",
+  },
+})
+  .sort()
+  .reduce((acc, key) => {
+    const value = ""; // TODO: document arguments
+    return { ...acc, [key]: value };
+  }, {});
+
+export async function parseAndEvalExpression(
+  exp: string,
+  params: any,
+  app?: AppInstance,
+  caller?: InstanceId,
+) {
+  return evalExpression(parseExpression(exp), params, app, caller);
+}
+
+export function checkSyntax(statement: string | SyntaxError): true | string {
+  if (statement === "syntax-error") {
+    return statement;
+  }
+  try {
+    parse(statement);
+    return true;
+  } catch (err: any) {
+    console.error("isSyntacticallyValid", err.message);
+    return err.message;
+  }
+}
+
+export async function evalExpression(
+  ast: Expression | SyntaxError,
+  params: any,
+  app?: AppImpl,
+  /**
+   * The service evaluating, so that what the expression starts elsewhere
+   * continues the run that service is in.
+   */
+  caller?: InstanceId,
+  /** Hears about every read that found nothing; see expressionEval.ts. */
+  onMissing?: OnMissing,
+) {
+  if (ast === "syntax-error") {
+    throw new Error("the expression does not parse");
+  }
+
+  const processRuntime =
+    app !== undefined
+      ? (rtName: string, params: any) =>
+          app?.processRuntimeByName?.(
+            rtName,
+            params,
+            caller ? app.currentContext?.(caller) : undefined,
+          )
+      : () => console.warn("processRuntime is not supported in this scope");
+
+  const getServiceConfig = (rtId: string, svcId: string, prop: string) =>
+    (window as any).hkp.getServiceConfig(rtId, svcId).then((x: any) => x[prop]); // window.hkp is untyped
+
+  return expEval(
+    ast,
+    {
+      ...params,
+      ...globalScope,
+      variables: app?.getRuntimeVariable() ?? {},
+      getServiceConfig,
+      processRuntime,
+    },
+    onMissing,
+  );
+}

package/bundle/hkp-frontend/src/runtime/browser/services/base/expressionEval.ts

@@ -0,0 +1,223 @@
+/**
+ * The expressions a board writes — a Map's terms, a Filter's predicate — and
+ * what evaluating one may reach.
+ *
+ * This is the boundary between a board, which somebody else may have written,
+ * and the process it runs in: on a hosted server, everyone the server lets in.
+ * It was the `expression-eval` package until its author stopped maintaining
+ * it; it is kept here so that it is read and changed like the security code it
+ * is (`docs/content/concepts/runtime.md`). Parsing is `jsep`'s, pinned.
+ *
+ * What an expression can do is what the scope it is given can do, and nothing
+ * else:
+ *
+ * - **No way to code.** Nothing here compiles a string, and the routes to
+ *   something that does — `constructor`, `prototype`, `__proto__`, and every
+ *   other `__`-prefixed member — are refused by name, however the name is
+ *   arrived at (`a.b`, `a["b"]`, `a[["b"]]`).
+ * - **No assignment.** The grammar has none, so an expression reads and calls
+ *   but never writes a property.
+ * - **Only the scope.** A name resolves to the scope's own property or to
+ *   nothing; what the scope inherits from `Object.prototype` is not a name.
+ *
+ * A member of nothing is nothing: `params.a.b` with no `a` is `undefined`, read
+ * as `params.a?.b` would be, rather than an error — the way hkp-rt and
+ * hkp-python read it, so a term evaluates alike wherever it runs. Whoever wants
+ * to know which reads came up empty passes `onMissing`.
+ *
+ * Twin of hkp-node's `src/expressionEval.ts`; the two are kept identical, so a
+ * term evaluates alike in either runtime.
+ */
+import jsep from "jsep";
+
+export type Expression = jsep.Expression;
+
+type Scope = Record<string, unknown>;
+
+/**
+ * Told the path of a read that found nothing — `params.titel` — once per
+ * chain: in `params.a.b.c` with no `a`, only `params.a` is reported.
+ */
+export type OnMissing = (path: string) => void;
+
+const BINARY: Record<string, (a: any, b: any) => unknown> = {
+  "|": (a, b) => a | b,
+  "^": (a, b) => a ^ b,
+  "&": (a, b) => a & b,
+  "==": (a, b) => a == b, // eslint-disable-line eqeqeq
+  "!=": (a, b) => a != b, // eslint-disable-line eqeqeq
+  "===": (a, b) => a === b,
+  "!==": (a, b) => a !== b,
+  "<": (a, b) => a < b,
+  ">": (a, b) => a > b,
+  "<=": (a, b) => a <= b,
+  ">=": (a, b) => a >= b,
+  "<<": (a, b) => a << b,
+  ">>": (a, b) => a >> b,
+  ">>>": (a, b) => a >>> b,
+  "+": (a, b) => a + b,
+  "-": (a, b) => a - b,
+  "*": (a, b) => a * b,
+  "/": (a, b) => a / b,
+  "%": (a, b) => a % b,
+};
+
+const UNARY: Record<string, (a: any) => unknown> = {
+  "-": (a) => -a,
+  "+": (a) => +a,
+  "~": (a) => ~a,
+  "!": (a) => !a,
+};
+
+/** Members that lead from a value to the code behind it. */
+const REFUSED_MEMBERS = new Set(["constructor", "prototype"]);
+
+/** Parses an expression; throws on one that does not parse. */
+export function parse(source: string): Expression {
+  return jsep(source);
+}
+
+/** The member a key names, or a refusal when it names a way out. */
+function memberKey(key: unknown): string | number {
+  if (typeof key === "number") {
+    return key;
+  }
+  // As a property access would read it: `a[["b"]]` is `a.b`.
+  const name = String(key);
+  if (REFUSED_MEMBERS.has(name) || name.startsWith("__")) {
+    throw new Error(`Access to member "${name}" disallowed.`);
+  }
+  return name;
+}
+
+/** How a read is named when it is reported: `params.items[0].title`. */
+function pathOf(node: Expression): string {
+  switch (node.type) {
+    case "Identifier":
+      return (node as jsep.Identifier).name;
+    case "ThisExpression":
+      return "this";
+    case "MemberExpression": {
+      const read = node as jsep.MemberExpression;
+      const object = pathOf(read.object);
+      if (!read.computed) {
+        return `${object}.${(read.property as jsep.Identifier).name}`;
+      }
+      return read.property.type === "Literal"
+        ? `${object}[${JSON.stringify((read.property as jsep.Literal).value)}]`
+        : `${object}[…]`;
+    }
+    default:
+      return "…";
+  }
+}
+
+function member(
+  node: jsep.MemberExpression,
+  scope: Scope,
+  onMissing?: OnMissing,
+): [unknown, unknown] {
+  const object = evaluate(node.object, scope, onMissing) as any;
+  const key = memberKey(
+    node.computed
+      ? evaluate(node.property, scope, onMissing)
+      : (node.property as jsep.Identifier).name,
+  );
+  const nothing = object === undefined || object === null;
+  const value = nothing ? undefined : object[key];
+  // A read past a link that came up empty was reported with it; one past a
+  // link that is there but null is reported itself.
+  const pastMissing =
+    object === undefined && node.object.type === "MemberExpression";
+  if (value === undefined && onMissing && !pastMissing) {
+    onMissing(pathOf(node));
+  }
+  return [object, value];
+}
+
+/**
+ * Evaluates a parsed expression with `scope` as everything it may name;
+ * `onMissing` hears about every read that found nothing.
+ */
+export function evaluate(
+  node: Expression,
+  scope: Scope,
+  onMissing?: OnMissing,
+): unknown {
+  switch (node.type) {
+    case "ArrayExpression":
+      return (node as jsep.ArrayExpression).elements.map((element) =>
+        evaluate(element, scope, onMissing),
+      );
+    case "BinaryExpression": {
+      const binary = node as jsep.BinaryExpression;
+      const operator = BINARY[binary.operator];
+      if (!operator) {
+        throw new Error(`Unsupported operator "${binary.operator}"`);
+      }
+      return operator(
+        evaluate(binary.left, scope, onMissing),
+        evaluate(binary.right, scope, onMissing),
+      );
+    }
+    case "LogicalExpression": {
+      const logical = node as jsep.LogicalExpression;
+      if (logical.operator === "||") {
+        return (
+          evaluate(logical.left, scope, onMissing) ||
+          evaluate(logical.right, scope, onMissing)
+        );
+      }
+      if (logical.operator === "&&") {
+        return (
+          evaluate(logical.left, scope, onMissing) &&
+          evaluate(logical.right, scope, onMissing)
+        );
+      }
+      throw new Error(`Unsupported operator "${logical.operator}"`);
+    }
+    case "CallExpression": {
+      const call = node as jsep.CallExpression;
+      let self: unknown;
+      let fn: unknown;
+      if (call.callee.type === "MemberExpression") {
+        [self, fn] = member(call.callee as jsep.MemberExpression, scope, onMissing);
+      } else {
+        fn = evaluate(call.callee, scope, onMissing);
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError(`${pathOf(call.callee)} is not a function`);
+      }
+      return fn.apply(
+        self,
+        call.arguments.map((argument) => evaluate(argument, scope, onMissing)),
+      );
+    }
+    case "ConditionalExpression": {
+      const conditional = node as jsep.ConditionalExpression;
+      return evaluate(conditional.test, scope, onMissing)
+        ? evaluate(conditional.consequent, scope, onMissing)
+        : evaluate(conditional.alternate, scope, onMissing);
+    }
+    case "Identifier": {
+      const name = (node as jsep.Identifier).name;
+      return Object.prototype.hasOwnProperty.call(scope, name) ? scope[name] : undefined;
+    }
+    case "Literal":
+      return (node as jsep.Literal).value;
+    case "MemberExpression":
+      return member(node as jsep.MemberExpression, scope, onMissing)[1];
+    case "ThisExpression":
+      return scope;
+    case "UnaryExpression": {
+      const unary = node as jsep.UnaryExpression;
+      const operator = UNARY[unary.operator];
+      if (!operator) {
+        throw new Error(`Unsupported operator "${unary.operator}"`);
+      }
+      return operator(evaluate(unary.argument, scope, onMissing));
+    }
+    default:
+      return undefined;
+  }
+}

package/bundle/hkp-frontend/src/runtime/browser/services/base/helpers.ts

@@ -0,0 +1,10 @@
+export function sleep(t: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, t);
+  });
+}
+
+export function roundWithNDecimals(x: number, n: number): number {
+  const m = n * 10;
+  return Math.round(x * m) / m;
+}

package/bundle/hkp-frontend/src/runtime/browser/services/base/index.ts

@@ -0,0 +1,37 @@
+import { parseExpression, evalExpression } from "./eval";
+import MapDescriptor from "./Map";
+import ReduceDescriptor from "./Reduce";
+import MatchFilterDescriptor from "./MatchFilter";
+import FilterDescriptor from "./Filter";
+import TimerDescriptor from "./Timer";
+import BatcherDescriptor from "./Batcher";
+import MonitorDescriptor from "./Monitor";
+
+// TODO: do we need this entry point at all?
+
+function createServiceFactory(rt: any, descriptor: any): any {
+  const { serviceId, serviceName, service: Service } = descriptor;
+  return {
+    serviceId,
+    serviceName,
+    create: (board: any, descriptor: any, id: string) => new Service(rt, board, descriptor, id),
+  };
+}
+
+function createRegistry(rt: any): any[] {
+  return [
+    createServiceFactory(rt, MapDescriptor),
+    createServiceFactory(rt, ReduceDescriptor),
+    createServiceFactory(rt, MatchFilterDescriptor),
+    createServiceFactory(rt, FilterDescriptor),
+    createServiceFactory(rt, TimerDescriptor),
+    createServiceFactory(rt, BatcherDescriptor),
+    createServiceFactory(rt, MonitorDescriptor),
+  ];
+}
+
+export default {
+  parseExpression,
+  evalExpression,
+  createRegistry,
+};

package/bundle/hkp-frontend/src/runtime/browser/services/camera/videoCapture.ts

@@ -0,0 +1,78 @@
+/**
+ * Getting frames out of a camera, apart from anything that draws.
+ *
+ * The Camera service holds no stream of its own. It captures through whatever
+ * mounted a video element and handed it a screenshooter — its service panel, or
+ * a facade's camera widget — because only something on screen can ask for the
+ * camera and show that it is on. Both need the same three steps, so they live
+ * here rather than in whichever grew them first.
+ */
+
+export async function startVideoStream(
+  video: HTMLVideoElement,
+  deviceId?: string,
+): Promise<MediaStream> {
+  if (!navigator.mediaDevices) {
+    throw new Error("Can not initialize video");
+  }
+  const constraints: MediaStreamConstraints = deviceId
+    ? { video: { deviceId } }
+    : { video: true };
+  const stream = await navigator.mediaDevices.getUserMedia(constraints);
+  video.srcObject = stream;
+  try {
+    await video.play();
+  } catch (err) {
+    // A browser can grant a stream yet refuse to attach/play it (headless and
+    // embedded webviews are common examples). Do not leak the granted device
+    // while reporting that failure to the UI.
+    stream.getTracks().forEach((track) => track.stop());
+    video.srcObject = null;
+    throw err;
+  }
+  return stream;
+}
+
+export function stopVideoStream(
+  stream: MediaStream | null,
+  video?: HTMLVideoElement | null,
+): void {
+  if (!stream) {
+    return;
+  }
+  stream.getTracks?.().forEach((track) => track.stop());
+  stream.getVideoTracks?.().forEach((track) => track.stop());
+  if (video) {
+    video.srcObject = null;
+  }
+}
+
+/**
+ * One frame, at the capture size rather than the size it is shown at — the
+ * picture the pipeline gets is not the picture on screen.
+ *
+ * The canvas is the caller's, held across calls: a board capturing several
+ * times a second would otherwise build one per frame.
+ */
+export function captureFrame(
+  video: HTMLVideoElement | null,
+  canvasRef: { current: HTMLCanvasElement | null },
+  width: number,
+  height: number,
+  format: string,
+): Promise<Blob | null> {
+  return new Promise<Blob | null>((resolve) => {
+    if (!canvasRef.current) {
+      canvasRef.current = document.createElement("canvas");
+    }
+    canvasRef.current.width = width;
+    canvasRef.current.height = height;
+    const ctx = canvasRef.current.getContext("2d");
+    if (!ctx || !video) {
+      resolve(null);
+      return;
+    }
+    ctx.drawImage(video, 0, 0, width, height);
+    canvasRef.current.toBlob(resolve, format);
+  });
+}

package/bundle/hkp-frontend/src/runtime/browser/services/changes-modes.ts

@@ -0,0 +1,9 @@
+/** When a change in the watched value lets the input through. */
+export const EMIT_MODES = ["change", "rise", "fall"] as const;
+export type EmitMode = (typeof EMIT_MODES)[number];
+
+export const EMIT_LABELS: { [mode in EmitMode]: string } = {
+  change: "Any change",
+  rise: "Becomes true",
+  fall: "Becomes false",
+};

package/bundle/hkp-frontend/src/runtime/browser/services/colorpalette.ts

@@ -0,0 +1,26 @@
+export const p1: string[] = ["264653", "2a9d8f", "e9c46a", "f4a261", "e76f51"];
+export const p2: string[] = [
+  "ffadad",
+  "ffd6a5",
+  "fdffb6",
+  "caffbf",
+  "9bf6ff",
+  "a0c4ff",
+  "bdb2ff",
+  "ffc6ff",
+  "fffffc",
+];
+export const p3: string[] = [
+  "f94144",
+  "f3722c",
+  "f8961e",
+  "f9844a",
+  "f9c74f",
+  "90be6d",
+  "43aa8b",
+  "4d908e",
+  "577590",
+  "277da1",
+];
+
+export const p: string[] = [...p1, ...p2, ...p3];

package/bundle/hkp-frontend/src/runtime/browser/services/detect/DetectionPreview.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useRef } from "react";
+
+import type { Face } from "../Detect";
+
+/** What Detect reports on each frame as `found`: the frame, and what was in it. */
+export type Found = {
+  faces: Face[];
+  frame: { width: number; height: number };
+  image: Blob | null;
+};
+
+/**
+ * The last frame Detect looked at, with what it found outlined. Drawn by the
+ * service's panel and by the facade's `detect` widget, from the same `found`
+ * notification.
+ */
+export default function DetectionPreview({
+  found,
+  width,
+}: {
+  found: Found;
+  width: number;
+}) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const { frame, faces, image } = found;
+  const scale = frame.width ? width / frame.width : 1;
+  const height = Math.round(frame.height * scale) || 1;
+
+  useEffect(() => {
+    const ctx = canvas.current?.getContext("2d");
+    if (!ctx) {
+      return;
+    }
+    let cancelled = false;
+    const draw = (bitmap: ImageBitmap | null) => {
+      if (cancelled) {
+        bitmap?.close();
+        return;
+      }
+      ctx.clearRect(0, 0, width, height);
+      if (bitmap) {
+        ctx.drawImage(bitmap, 0, 0, width, height);
+        bitmap.close();
+      }
+      ctx.lineWidth = 2;
+      ctx.strokeStyle = "#22c55e";
+      for (const face of faces) {
+        ctx.strokeRect(
+          face.box.x * scale,
+          face.box.y * scale,
+          face.box.width * scale,
+          face.box.height * scale,
+        );
+      }
+    };
+    if (image) {
+      createImageBitmap(image).then(draw, () => draw(null));
+    } else {
+      draw(null);
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [width, height, scale, faces, image]);
+
+  return (
+    <canvas
+      ref={canvas}
+      role="img"
+      aria-label={`${faces.length} ${faces.length === 1 ? "face" : "faces"} found`}
+      width={width}
+      height={height}
+      style={{ width, height, background: "#111", borderRadius: 6 }}
+    />
+  );
+}