@nyte-ai/plugin 0.0.25-nightly.20261101.43 → 0.0.27

package/dist/src/browser-client.js

@@ -0,0 +1,374 @@
+// src/browser-client.ts
+import { onlyNyteAppHas } from "@nyte-ai/core";
+import { asId, compile, idSchema, isJson, SdkError } from "@nyte-ai/schema";
+import { Type } from "typebox";
+import browserTools from "@nyte-ai/plugin/core/browser-tools";
+var BROWSER_ACTION = {
+  name: "browser",
+  summary: "Drives the page a chat's agent holds in this app's browser.",
+  input: { type: "object" }
+};
+var PERFORM_MS = 30000;
+var SessionField = idSchema();
+var ref = Type.String();
+var OwnerType = Type.Union([
+  Type.Object({ kind: Type.Literal("home") }),
+  Type.Object({ kind: Type.Literal("project"), path: Type.String() })
+]);
+var WaitType = Type.Union([
+  Type.Object({ until: Type.Literal("load") }),
+  Type.Object({ until: Type.Literal("text"), text: Type.String() }),
+  Type.Object({ until: Type.Literal("gone"), text: Type.String() }),
+  Type.Object({ until: Type.Literal("time"), seconds: Type.Number() })
+]);
+var BrowserCallType = Type.Union([
+  Type.Object({
+    method: Type.Literal("open"),
+    session: SessionField,
+    owner: OwnerType,
+    url: Type.String()
+  }),
+  Type.Object({ method: Type.Literal("snapshot"), session: SessionField, ref: Type.Optional(ref) }),
+  Type.Object({
+    method: Type.Literal("click"),
+    session: SessionField,
+    ref,
+    expect: Type.String(),
+    button: Type.Optional(Type.Enum(["left", "right", "middle"])),
+    double: Type.Optional(Type.Boolean())
+  }),
+  Type.Object({
+    method: Type.Literal("type"),
+    session: SessionField,
+    ref,
+    text: Type.String(),
+    expect: Type.String(),
+    clear: Type.Optional(Type.Boolean()),
+    submit: Type.Optional(Type.Boolean())
+  }),
+  Type.Object({
+    method: Type.Literal("press"),
+    session: SessionField,
+    key: Type.String(),
+    ref: Type.Optional(ref)
+  }),
+  Type.Object({
+    method: Type.Literal("scroll"),
+    session: SessionField,
+    direction: Type.Enum(["up", "down", "top", "bottom"]),
+    ref: Type.Optional(ref),
+    pages: Type.Optional(Type.Number())
+  }),
+  Type.Object({ method: Type.Literal("wait"), session: SessionField, wait: WaitType }),
+  Type.Object({
+    method: Type.Literal("console"),
+    session: SessionField,
+    limit: Type.Integer({ minimum: 1 }),
+    clear: Type.Optional(Type.Boolean())
+  }),
+  Type.Object({
+    method: Type.Literal("evaluate"),
+    session: SessionField,
+    expression: Type.String(),
+    ref: Type.Optional(ref)
+  }),
+  Type.Object({ method: Type.Literal("capture"), session: SessionField }),
+  Type.Object({ method: Type.Literal("release"), session: SessionField })
+]);
+var PageStateType = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  loading: Type.Boolean(),
+  snapshot: Type.Number(),
+  nodes: Type.Array(Type.Object({
+    ref: Type.String(),
+    role: Type.String(),
+    name: Type.String(),
+    editable: Type.Optional(Type.Boolean())
+  }))
+});
+var FailureType = Type.Object({
+  kind: Type.Enum([
+    "stale_document",
+    "unknown_ref",
+    "detached",
+    "not_visible",
+    "occluded",
+    "no_window",
+    "closed",
+    "crashed"
+  ])
+});
+var ActionAnswerType = Type.Union([
+  Type.Object({ kind: Type.Literal("ok"), state: PageStateType }),
+  Type.Object({ kind: Type.Literal("failed"), failure: FailureType })
+]);
+var EvaluateAnswerType = Type.Union([
+  Type.Object({ kind: Type.Literal("value"), json: Type.String() }),
+  Type.Object({ kind: Type.Literal("threw"), message: Type.String() })
+]);
+var ConsoleAnswerType = Type.Array(Type.Object({
+  level: Type.Enum(["error", "warning", "info", "debug"]),
+  message: Type.String(),
+  at: Type.Number()
+}));
+var CaptureAnswerType = Type.Union([Type.Null(), Type.Object({ png: Type.String() })]);
+var answers = {
+  action: compile(ActionAnswerType),
+  evaluate: compile(EvaluateAnswerType),
+  console: compile(ConsoleAnswerType),
+  capture: compile(CaptureAnswerType)
+};
+var UNICODE_FORGERY = /[\u2028\u2029\u202a-\u202e]/g;
+var CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/g;
+function sanitizeLine(text) {
+  return text.replace(CONTROL_CHARACTERS, "").replace(UNICODE_FORGERY, "");
+}
+function sessionSurfaceId(sessionId) {
+  return `stage:session:${encodeURIComponent(sessionId)}`;
+}
+function clientBrowserPlugins(actions, home) {
+  return [
+    browserTools,
+    {
+      id: "client-browser",
+      activate(api) {
+        const owner = api.env.cwd === home ? { kind: "home" } : { kind: "project", path: api.env.cwd };
+        const browser = sessionBrowser(actions, api.session.sessionId, owner);
+        api.wrapEnv((inner) => ({
+          identity: inner.identity,
+          cwd: inner.cwd,
+          files: inner.files,
+          exec: (command, options) => inner.exec(command, options),
+          close: () => inner.close(),
+          browser
+        }));
+        api.signal.addEventListener("abort", () => {
+          if (actions.offered(BROWSER_ACTION.name))
+            ask(actions, { method: "release", session: api.session.sessionId }).catch(() => {
+              return;
+            });
+        }, { once: true });
+      }
+    }
+  ];
+}
+function sessionBrowser(actions, session, owner) {
+  const id = asId(sessionSurfaceId(session));
+  let state = null;
+  const act = async (call) => decode(answers.action, await ask(actions, call));
+  const settle = (answer) => {
+    if (answer.kind === "failed")
+      return failureOutcome(answer.failure, state);
+    state = answer.state;
+    return { kind: "applied", snapshot: toPageSnapshot(answer.state) };
+  };
+  const expect = (target) => state?.nodes.find((node) => node.ref === target)?.name ?? "";
+  const script = async (expression) => {
+    const ran = decode(answers.evaluate, await ask(actions, { method: "evaluate", session, expression }));
+    if (ran.kind === "threw")
+      return { kind: "refused", reason: "policy" };
+    return settle(await act({ method: "wait", session, wait: { until: "load" } }));
+  };
+  const view = () => ({
+    id,
+    url: sanitizeLine(state?.url ?? ""),
+    title: sanitizeLine(state?.title ?? ""),
+    loading: state?.loading ?? false,
+    revision: asId(String(state?.snapshot ?? 0)),
+    canGoBack: false,
+    canGoForward: false
+  });
+  const pages = () => {
+    offeredOrThrow(actions);
+    return state === null ? [] : [{ id, url: state.url, title: state.title, holders: 1 }];
+  };
+  const page = {
+    id,
+    view: async () => view(),
+    async* watch() {
+      yield view();
+    },
+    async snapshot(input) {
+      const answer = await act({ method: "snapshot", session, ref: input?.ref });
+      if (answer.kind === "failed")
+        throw new SdkError("unavailable", `The page cannot be read: ${answer.failure.kind}.`);
+      state = answer.state;
+      return toPageSnapshot(answer.state);
+    },
+    navigate: async (url) => settle(await act({ method: "open", session, owner, url })),
+    back: () => script("history.back()"),
+    forward: () => script("history.forward()"),
+    reload: () => script("location.reload()"),
+    stopLoading: () => script("window.stop()"),
+    click: async (input) => settle(await act({
+      method: "click",
+      session,
+      ref: input.ref,
+      expect: expect(input.ref),
+      button: input.button,
+      double: input.double
+    })),
+    type: async (input) => settle(await act({
+      method: "type",
+      session,
+      ref: input.ref,
+      text: input.text,
+      clear: input.clear,
+      submit: input.submit,
+      expect: expect(input.ref)
+    })),
+    press: async (input) => settle(await act({ method: "press", session, key: input.key, ref: input.ref })),
+    scroll: async (input) => settle(await act({
+      method: "scroll",
+      session,
+      direction: input.direction,
+      ref: input.ref,
+      pages: input.pages
+    })),
+    async wait(condition) {
+      if (condition.kind === "loaded")
+        return settle(await act({ method: "wait", session, wait: { until: "load" } }));
+      if (condition.kind === "delay")
+        return settle(await act({
+          method: "wait",
+          session,
+          wait: { until: "time", seconds: Math.max(0.1, condition.ms / 1000) }
+        }));
+      return settle(await act({
+        method: "wait",
+        session,
+        wait: { until: condition.present ? "text" : "gone", text: condition.text }
+      }));
+    },
+    async console(input) {
+      const entries = decode(answers.console, await ask(actions, {
+        method: "console",
+        session,
+        limit: input?.limit ?? 50,
+        clear: input?.clear
+      }));
+      return entries.map((entry) => ({
+        level: entry.level === "warning" ? "warn" : entry.level === "debug" ? "log" : entry.level,
+        text: entry.message,
+        at: entry.at
+      }));
+    },
+    async capture() {
+      const captured = decode(answers.capture, await ask(actions, { method: "capture", session }));
+      if (captured === null)
+        throw new SdkError("unavailable", "The page could not be captured.");
+      return pngReader(Uint8Array.fromBase64(captured.png));
+    },
+    async evaluate(expression, options) {
+      const result = decode(answers.evaluate, await ask(actions, { method: "evaluate", session, expression, ref: options?.ref }));
+      if (result.kind === "threw")
+        return result;
+      const value = JSON.parse(result.json);
+      return { kind: "value", value: isJson(value) ? value : result.json };
+    },
+    close: async () => {
+      return;
+    },
+    [Symbol.asyncDispose]: async () => {
+      return;
+    }
+  };
+  return {
+    async open(input) {
+      const outcome = settle(await act({ method: "open", session, owner, url: input.url }));
+      if (outcome.kind !== "applied")
+        throw new SdkError("unavailable", `The page did not open: ${outcome.kind}.`);
+      return page;
+    },
+    async adopt(pageId) {
+      offeredOrThrow(actions);
+      if (pageId !== id || state === null)
+        throw new SdkError("unknown", "No page has this id.");
+      return page;
+    },
+    list: async () => pages(),
+    async* watch() {
+      yield pages();
+    }
+  };
+}
+async function ask(actions, call) {
+  offeredOrThrow(actions);
+  const input = JSON.parse(JSON.stringify(call));
+  if (!isJson(input))
+    throw new SdkError("internal", "A browser call did not encode as JSON.");
+  return actions.perform(BROWSER_ACTION.name, input, PERFORM_MS).catch((error) => {
+    if (error instanceof SdkError && error.code === "not_supported")
+      throw unavailable();
+    throw error;
+  });
+}
+function offeredOrThrow(actions) {
+  if (!actions.offered(BROWSER_ACTION.name))
+    throw unavailable();
+}
+function unavailable() {
+  return new SdkError("unavailable", onlyNyteAppHas("The browser", [browserTools.id]));
+}
+function decode(checker, value) {
+  if (!checker.Check(value))
+    throw new SdkError("invalid", "The app answered a browser call with something unreadable.");
+  return value;
+}
+function failureOutcome(failure, state) {
+  switch (failure.kind) {
+    case "stale_document":
+      return { kind: "stale", revision: asId(String(state?.snapshot ?? 0)) };
+    case "unknown_ref":
+    case "detached":
+      return { kind: "refused", reason: "unknown-ref" };
+    case "occluded":
+      return { kind: "refused", reason: "occluded" };
+    case "not_visible":
+    case "no_window":
+      return { kind: "refused", reason: "not-visible" };
+    case "closed":
+      return { kind: "closed", reason: "released" };
+    case "crashed":
+      return { kind: "closed", reason: "crashed" };
+    default: {
+      const _exhaustive = failure.kind;
+      return _exhaustive;
+    }
+  }
+}
+function toPageSnapshot(state) {
+  return {
+    revision: asId(String(state.snapshot)),
+    nodes: state.nodes.map((node) => ({
+      ref: node.ref,
+      role: sanitizeLine(node.role),
+      name: sanitizeLine(node.name),
+      editable: node.editable === true,
+      depth: 0
+    }))
+  };
+}
+function pngReader(bytes) {
+  return {
+    size: bytes.byteLength,
+    mime: "image/png",
+    async* chunks() {
+      yield bytes;
+    },
+    close: async () => {
+      return;
+    },
+    [Symbol.asyncDispose]: async () => {
+      return;
+    }
+  };
+}
+export {
+  BROWSER_ACTION,
+  BrowserCallType,
+  clientBrowserPlugins,
+  sanitizeLine,
+  sessionSurfaceId
+};

package/dist/src/canvas/canvas-client.d.ts

@@ -0,0 +1,71 @@
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import type { ClientActions } from "../browser-client.ts";
+import type { CanvasPreviewer } from "./canvas-preview.ts";
+/**
+ * The action an app offers to render a canvas preview in its own renderer;
+ * its input is a `CanvasPreviewRequest`, its answer a
+ * `CanvasPreviewAnswer`.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare const CANVAS_PREVIEW_ACTION: {
+    readonly name: "canvas.preview";
+    readonly summary: "Renders a canvas off-screen in this app and reports what it saw.";
+    readonly input: {
+        readonly type: "object";
+    };
+};
+/**
+ * What the host sends the preview action.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare const CanvasPreviewCallType: Type.TObject<{
+    module: Type.TObject<{
+        runtime: Type.TNumber;
+        code: Type.TString;
+        title: Type.TString;
+    }>;
+    theme: Type.TEnum<["light", "dark"]>;
+}>;
+/**
+ * What the preview action answers: the outcome, its PNG as base64.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare const CanvasPreviewAnswerType: Type.TUnion<[Type.TObject<{
+    kind: Type.TLiteral<"rendered">;
+    report: Type.TObject<{
+        png: Type.TString;
+        heights: Type.TObject<{
+            chat: Type.TNumber;
+            phone: Type.TNumber;
+        }>;
+        errors: Type.TArray<Type.TObject<{
+            phase: Type.TEnum<["load", "render"]>;
+            message: Type.TString;
+            stack: Type.TUnion<[Type.TString, Type.TNull]>;
+        }>>;
+        console: Type.TArray<Type.TObject<{
+            level: Type.TString;
+            text: Type.TString;
+        }>>;
+    }>;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"unavailable">;
+    reason: Type.TString;
+}>]>;
+export type CanvasPreviewAnswer = Static<typeof CanvasPreviewAnswerType>;
+/**
+ * Returns a previewer that renders in the connected app that offers
+ * `CANVAS_PREVIEW_ACTION`, and in `fallback` while none does. The app
+ * answers within 30 seconds, the longest a client action waits.
+ *
+ * @category plugins
+ * @since 0.1.0
+ */
+export declare function clientCanvasPreview(actions: ClientActions, fallback: CanvasPreviewer): CanvasPreviewer;

package/dist/src/canvas/canvas-client.js

@@ -0,0 +1,70 @@
+// src/canvas/canvas-client.ts
+import { compile, SdkError } from "@nyte-ai/schema";
+import { Type } from "typebox";
+var CANVAS_PREVIEW_ACTION = {
+  name: "canvas.preview",
+  summary: "Renders a canvas off-screen in this app and reports what it saw.",
+  input: { type: "object" }
+};
+var PERFORM_MS = 30000;
+var CanvasPreviewCallType = Type.Object({
+  module: Type.Object({ runtime: Type.Number(), code: Type.String(), title: Type.String() }),
+  theme: Type.Enum(["light", "dark"])
+});
+var CanvasPreviewAnswerType = Type.Union([
+  Type.Object({
+    kind: Type.Literal("rendered"),
+    report: Type.Object({
+      png: Type.String(),
+      heights: Type.Object({ chat: Type.Number(), phone: Type.Number() }),
+      errors: Type.Array(Type.Object({
+        phase: Type.Enum(["load", "render"]),
+        message: Type.String(),
+        stack: Type.Union([Type.String(), Type.Null()])
+      })),
+      console: Type.Array(Type.Object({ level: Type.String(), text: Type.String() }))
+    })
+  }),
+  Type.Object({ kind: Type.Literal("unavailable"), reason: Type.String() })
+]);
+var previewAnswers = compile(CanvasPreviewAnswerType);
+function clientCanvasPreview(actions, fallback) {
+  return async (request, signal) => {
+    if (!actions.offered(CANVAS_PREVIEW_ACTION.name))
+      return fallback(request, signal);
+    const answered = await actions.perform(CANVAS_PREVIEW_ACTION.name, previewInput(request), PERFORM_MS).catch((error) => {
+      if (error instanceof SdkError && error.code === "not_supported")
+        return null;
+      throw error;
+    });
+    if (answered === null)
+      return fallback(request, signal);
+    if (!previewAnswers.Check(answered))
+      throw new SdkError("invalid", "The app answered a canvas preview with something unreadable.");
+    return readAnswer(answered);
+  };
+}
+function previewInput(request) {
+  return {
+    module: {
+      runtime: request.module.runtime,
+      code: request.module.code,
+      title: request.module.title
+    },
+    theme: request.theme
+  };
+}
+function readAnswer(answer) {
+  if (answer.kind === "unavailable")
+    return answer;
+  return {
+    kind: "rendered",
+    report: { ...answer.report, png: Uint8Array.fromBase64(answer.report.png) }
+  };
+}
+export {
+  CANVAS_PREVIEW_ACTION,
+  CanvasPreviewAnswerType,
+  CanvasPreviewCallType,
+  clientCanvasPreview
+};

package/dist/src/canvas/canvas-compile.d.ts

@@ -1,10 +1,3 @@
-/**
- * Returns what the compiler answers for one canvas: the ESM module to ship,
- * with the runtime it targets, or the diagnostics the model fixes.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CompileOutcome = {
     readonly kind: "compiled";
     readonly code: string;
@@ -13,41 +6,14 @@ export type CompileOutcome = {
     readonly kind: "failed";
     readonly errors: readonly CompileError[];
 };
-/**
- * Returns one diagnostic, positioned in a source file when the compiler
- * knows where; `file` is null for one about the canvas as a whole.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CompileError = {
     readonly file: string | null;
     readonly line: number | null;
     readonly column: number | null;
     readonly text: string;
 };
-/**
- * Returns a canvas's other files, keyed by their path from `main.tsx`'s
- * folder, such as `chart.tsx` or `lib/scale.ts`.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasFiles = Readonly<Record<string, string>>;
-/**
- * The relative specifiers a file imports at run time; type-only imports are stripped first.
- *
- * @category plugins
- */
 export declare function localImports(file: string, source: string): Promise<readonly string[]>;
-/**
- * Compiles a canvas, `source` as `main.tsx` (or `options.entry`) plus the
- * `files` it imports, to the one module the shell imports. The caps default
- * to the contract's; a test narrows them.
- *
- * @category plugins
- * @since 0.1.0
- */
 export declare function compileCanvas(source: string, files?: CanvasFiles, options?: {
     readonly source?: number;
     readonly code?: number;

package/dist/src/canvas/canvas-libraries.d.ts

@@ -1,9 +1,3 @@
-/**
- * The libraries a canvas may import, each pinned in packages/canvas and
- * served by the shell as its own chunk, with every name its module exports.
- * Written by `packages/canvas/scripts/library-exports.mjs`; a canvas test
- * checks it against the installed packages.
- */
 export declare const CANVAS_LIBRARIES: {
     readonly three: {
         readonly version: "0.186.1";

package/dist/src/canvas/canvas-preview.d.ts

@@ -1,50 +1,21 @@
 import type { CanvasModule } from "./canvas-protocol.ts";
-/** The widths a preview measures at, in CSS pixels: the desktop chat column (its 840 px measure less the gutters) and a phone's. */
 export declare const CANVAS_PREVIEW_WIDTHS: {
     readonly chat: 808;
     readonly phone: 358;
 };
-/**
- * Returns what a previewer renders: the compiled module and the theme to
- * show it in.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewRequest = {
     readonly module: CanvasModule;
     readonly theme: "light" | "dark";
 };
-/**
- * Returns one error the shell reported while the preview ran, its message
- * ending in the canvas file and line when the stack named one.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewError = {
     readonly phase: "load" | "render";
     readonly message: string;
     readonly stack: string | null;
 };
-/**
- * Returns one console call the canvas made while the preview ran.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewLog = {
     readonly level: string;
     readonly text: string;
 };
-/**
- * Returns what a preview saw: a PNG of the canvas at the chat column's
- * width, its height there and at a phone's (`CANVAS_PREVIEW_WIDTHS`), its
- * errors and its console.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewReport = {
     readonly png: Uint8Array;
     readonly heights: {
@@ -54,13 +25,6 @@ export type CanvasPreviewReport = {
     readonly errors: readonly CanvasPreviewError[];
     readonly console: readonly CanvasPreviewLog[];
 };
-/**
- * Returns a previewer's answer: the report, or why this host cannot render
- * a preview (no renderer installed, the renderer failed to start).
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewOutcome = {
     readonly kind: "rendered";
     readonly report: CanvasPreviewReport;
@@ -68,40 +32,11 @@ export type CanvasPreviewOutcome = {
     readonly kind: "unavailable";
     readonly reason: string;
 };
-/**
- * Renders a compiled canvas off-screen in the real shell. A host passes one
- * to `canvasPlugin` to give the model `canvas_preview`, which gives each
- * preview 45 seconds. When `signal` aborts (past that, or the turn
- * stopped), the previewer tears its renderer down, so a canvas that hangs
- * its page holds up no later preview.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewer = (request: CanvasPreviewRequest, signal: AbortSignal) => Promise<CanvasPreviewOutcome>;
-/**
- * Returns the page a previewer loaded the shell in, top-level, for
- * `runCanvasPreview` to drive: `evaluate` runs an expression in the page
- * and resolves with its JSON-safe value (awaiting a promise), `resize` sets
- * the viewport in CSS pixels, `capture` takes a PNG of the viewport.
- *
- * @category plugins
- * @since 0.1.0
- */
 export type CanvasPreviewPage = {
     evaluate(expression: string): Promise<unknown>;
     resize(width: number, height: number): Promise<void>;
     capture(): Promise<Uint8Array>;
 };
-/**
- * Runs a preview on a page that has loaded the shell: installs the harness
- * (retrying while the shell's script has not run yet), settles at the chat
- * column's width and captures it there, then settles again at a phone's
- * width for its height.
- *
- * @category plugins
- * @since 0.1.0
- */
 export declare function runCanvasPreview(page: CanvasPreviewPage, request: CanvasPreviewRequest): Promise<CanvasPreviewReport>;
-/** Returns the preview as the model reads it beside the screenshot: heights, errors, console. */
 export declare function describeCanvasPreview(report: CanvasPreviewReport): string;