paseo-plugin-genui 0.0.0-stage → 0.1.0

package/shared/logic/widget-logic.ts

@@ -0,0 +1,163 @@
+// Pure logic behind the self-contained widgets (Timer, Quiz, Flashcards):
+// no React, no DOM, so it is unit-testable without the host modules.
+import type { Value } from "../core/types";
+import { isObject, isScalar, list, optionalText, text } from "./values";
+
+// ── Timer ────────────────────────────────────────────────────────────────
+
+/**
+ * A run/pause clock as timestamps, never as a tick count, so it stays right
+ * when the tab is backgrounded and intervals are throttled.
+ */
+export interface Clock {
+  /** Milliseconds accumulated over finished runs. */
+  readonly banked: number;
+  /** When the current run started (epoch ms), or null while stopped. */
+  readonly startedAt: number | null;
+}
+
+export const STOPPED: Clock = { banked: 0, startedAt: null };
+
+export function elapsedMs(clock: Clock, now: number): number {
+  return clock.banked + (clock.startedAt === null ? 0 : Math.max(0, now - clock.startedAt));
+}
+
+export function startClock(clock: Clock, now: number): Clock {
+  return clock.startedAt === null ? { banked: clock.banked, startedAt: now } : clock;
+}
+
+export function pauseClock(clock: Clock, now: number): Clock {
+  return clock.startedAt === null ? clock : { banked: elapsedMs(clock, now), startedAt: null };
+}
+
+/** Milliseconds left of a `totalMs` countdown, never below zero. */
+export function remainingMs(clock: Clock, totalMs: number, now: number): number {
+  return Math.max(0, totalMs - elapsedMs(clock, now));
+}
+
+/**
+ * `mm:ss`, or `h:mm:ss` from an hour up (or always, with `hours`, so a long
+ * countdown keeps one width as it crosses the hour).
+ */
+export function formatClock(totalSeconds: number, hours = false): string {
+  const whole = Number.isFinite(totalSeconds) ? Math.max(0, Math.floor(totalSeconds)) : 0;
+  const h = Math.floor(whole / 3600);
+  const m = Math.floor((whole % 3600) / 60);
+  const s = whole % 60;
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return h > 0 || hours ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`;
+}
+
+/** The countdown readout: a started second still shows until it is fully spent. */
+export function countdownSeconds(remaining: number): number {
+  return Math.ceil(remaining / 1000);
+}
+
+// ── Quiz ─────────────────────────────────────────────────────────────────
+
+export interface QuizQuestion {
+  readonly q: string;
+  readonly options: readonly string[];
+  /** 0-based index into `options`. */
+  readonly answer: number;
+  readonly why: string | null;
+}
+
+/**
+ * The correct option's index: a 0-based integer in range, or the option's
+ * text (exact first, then ignoring case and surrounding space).
+ */
+export function resolveAnswer(answer: unknown, options: readonly string[]): number | null {
+  if (typeof answer === "number") {
+    return Number.isInteger(answer) && answer >= 0 && answer < options.length ? answer : null;
+  }
+  if (typeof answer !== "string") return null;
+  const exact = options.indexOf(answer);
+  if (exact >= 0) return exact;
+  const wanted = answer.trim().toLowerCase();
+  if (wanted === "") return null;
+  const loose = options.findIndex((option) => option.trim().toLowerCase() === wanted);
+  return loose >= 0 ? loose : null;
+}
+
+/** One question, or null when it cannot be asked (no prompt, under two options, no valid answer). */
+export function parseQuestion(item: unknown): QuizQuestion | null {
+  if (!isObject(item)) return null;
+  const q = text(item.q).trim();
+  const rawOptions: readonly unknown[] = Array.isArray(item.options) ? item.options : [];
+  if (q === "" || rawOptions.length < 2 || !rawOptions.every(isScalar)) return null;
+  const options = rawOptions.map(text);
+  if (options.some((option) => option.trim() === "")) return null;
+  const answer = resolveAnswer(item.answer, options);
+  if (answer === null) return null;
+  const why = optionalText(item.why)?.trim() || null;
+  return { q, options, answer, why };
+}
+
+export function parseQuestions(items: Value | undefined): {
+  questions: QuizQuestion[];
+  skipped: number;
+} {
+  const all = list(items);
+  const questions = all.map(parseQuestion).filter((question) => question !== null);
+  return { questions, skipped: all.length - questions.length };
+}
+
+/** How many picks match their question's answer; unanswered questions count as wrong. */
+export function quizScore(
+  questions: readonly QuizQuestion[],
+  picks: readonly (number | null | undefined)[],
+): number {
+  return questions.reduce((sum, question, index) => sum + (picks[index] === question.answer ? 1 : 0), 0);
+}
+
+// ── Flashcards ───────────────────────────────────────────────────────────
+
+export interface Flashcard {
+  readonly front: string;
+  readonly back: string;
+}
+
+/** Cards with a front; a missing back is shown as empty rather than dropped. */
+export function parseCards(items: Value | undefined): Flashcard[] {
+  const cards: Flashcard[] = [];
+  const entries: readonly unknown[] = list(items);
+  for (const item of entries) {
+    if (!isObject(item)) continue;
+    const front = text(item.front).trim();
+    if (front === "") continue;
+    cards.push({ front, back: text(item.back).trim() });
+  }
+  return cards;
+}
+
+/**
+ * A viewing order for `count` cards built on `order`: positions that no
+ * longer exist are dropped and new ones (cards still streaming in) appended.
+ */
+export function reconcileOrder(order: readonly number[], count: number): number[] {
+  const seen = new Set<number>();
+  const kept = order.filter((index) => {
+    const keep = Number.isInteger(index) && index >= 0 && index < count && !seen.has(index);
+    seen.add(index);
+    return keep;
+  });
+  for (let index = 0; index < count; index++) if (!seen.has(index)) kept.push(index);
+  return kept;
+}
+
+/**
+ * A Fisher–Yates permutation of `order`. A shuffle that lands on the same
+ * order would look like a dead button, so that case swaps the first two.
+ */
+export function shuffleOrder(order: readonly number[], random: () => number = Math.random): number[] {
+  const result = [...order];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(random() * (i + 1));
+    [result[i], result[j]] = [result[j]!, result[i]!];
+  }
+  if (result.length > 1 && result.every((value, index) => value === order[index])) {
+    [result[0], result[1]] = [result[1]!, result[0]!];
+  }
+  return result;
+}

package/shared/rpc.ts

@@ -0,0 +1,252 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import type { EnvironmentDetailResult } from "./core/environments";
+import {
+  MAX_PATH_FILTERS,
+  MAX_THREAD_IDS,
+  type ChangesResult,
+  type CommitsResult,
+  type EnvironmentsResult,
+  type PatchesResult,
+  type PullRequestResult,
+  type ThreadsResult,
+} from "./core/project";
+import type { Value } from "./core/types";
+
+export const MAX_TILE_ZOOM = 19;
+
+export const foundImageSchema = z.object({
+  url: z.string(),
+  width: z.number(),
+  height: z.number(),
+  title: z.string(),
+  creator: z.string(),
+  license: z.string(),
+  licenseUrl: z.string().nullable(),
+  sourceUrl: z.string(),
+});
+
+export type FoundImage = z.infer<typeof foundImageSchema>;
+
+export const locatedSchema = z.object({
+  lat: z.number().min(-90).max(90),
+  lng: z.number().min(-180).max(180),
+});
+
+export type Located = z.infer<typeof locatedSchema>;
+
+const filePath = z.string().min(1).max(1024);
+const agentIdSchema = z.string().min(1).max(128);
+const blockKeySchema = z.string().min(1).max(512).nullable();
+
+const loadedDataSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), value: z.custom<Value>() }),
+  z.object({ ok: z.literal(false), error: z.string() }),
+]);
+
+const loadedImageSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), dataUrl: z.string() }),
+  z.object({ ok: z.literal(false), error: z.string(), off: z.boolean().optional() }),
+]);
+
+const webFailureSchema = z.object({
+  ok: z.literal(false),
+  error: z.string(),
+  off: z.boolean().optional(),
+});
+
+const webImageSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), dataUrl: z.string() }),
+  webFailureSchema,
+]);
+
+export const loadDataRpc = defineRpc({
+  name: "genui.load_data",
+  input: z.object({ agentId: agentIdSchema, path: filePath, raw: z.boolean().optional() }),
+  output: loadedDataSchema,
+});
+
+export const loadImageRpc = defineRpc({
+  name: "genui.load_image",
+  input: z.object({ agentId: agentIdSchema, path: filePath }),
+  output: loadedImageSchema,
+});
+
+export const loadAudioRpc = defineRpc({
+  name: "genui.load_audio",
+  input: z.object({ agentId: agentIdSchema, path: filePath }),
+  output: loadedImageSchema,
+});
+
+export const renderMarkdownRpc = defineRpc({
+  name: "genui.render_markdown",
+  input: z.object({ agentId: agentIdSchema, text: z.string() }),
+  output: z.object({ markdown: z.string() }),
+});
+
+export const checkUiRpc = defineRpc({
+  name: "genui.check_ui",
+  input: z.object({ agentId: agentIdSchema, spec: z.string().min(1).max(20_000) }),
+  output: z.object({ ok: z.boolean(), report: z.string() }),
+});
+
+export const uiExamplesRpc = defineRpc({
+  name: "genui.ui_examples",
+  input: z.object({ components: z.array(z.string().min(1).max(40)).min(1).max(6) }),
+  output: z.object({ ok: z.boolean(), text: z.string() }),
+});
+
+export const galleryListRpc = defineRpc({
+  name: "genui.gallery_list",
+  input: z.object({}),
+  output: z.object({ names: z.array(z.string()) }),
+});
+
+export const galleryGetRpc = defineRpc({
+  name: "genui.gallery_get",
+  input: z.object({ name: z.string().min(1).max(200) }),
+  output: z.object({ source: z.string() }),
+});
+
+export const galleryDataRpc = defineRpc({
+  name: "genui.gallery_data",
+  input: z.object({ path: filePath, raw: z.boolean().optional() }),
+  output: loadedDataSchema,
+});
+
+export const galleryImageRpc = defineRpc({
+  name: "genui.gallery_image",
+  input: z.object({ path: filePath }),
+  output: loadedImageSchema,
+});
+
+export const galleryAudioRpc = defineRpc({
+  name: "genui.gallery_audio",
+  input: z.object({ path: filePath }),
+  output: loadedImageSchema,
+});
+
+export const sketchFontRpc = defineRpc({
+  name: "genui.sketch_font",
+  input: z.object({}),
+  output: z.object({ dataUrl: z.string() }),
+});
+
+export const webImageRpc = defineRpc({
+  name: "genui.web_image",
+  input: z.object({ url: z.string().min(1).max(2048) }),
+  output: webImageSchema,
+});
+
+export const webSearchRpc = defineRpc({
+  name: "genui.web_search",
+  input: z.object({ query: z.string().min(1).max(200) }),
+  output: z.discriminatedUnion("ok", [
+    z.object({ ok: z.literal(true), image: foundImageSchema }),
+    webFailureSchema,
+  ]),
+});
+
+export const webGeocodeRpc = defineRpc({
+  name: "genui.web_geocode",
+  input: z.object({ name: z.string().min(1).max(200), near: locatedSchema.nullable() }),
+  output: z.discriminatedUnion("ok", [
+    locatedSchema.extend({ ok: z.literal(true) }),
+    webFailureSchema,
+  ]),
+});
+
+export const webTileRpc = defineRpc({
+  name: "genui.web_tile",
+  input: z.object({
+    z: z.number().int().min(0).max(MAX_TILE_ZOOM),
+    x: z.number().int().min(0),
+    y: z.number().int().min(0),
+  }),
+  output: webImageSchema,
+});
+
+export const projectChangesRpc = defineRpc({
+  name: "genui.project_changes",
+  input: z.object({
+    agentId: agentIdSchema,
+    target: z.string().max(64).nullable(),
+    paths: z.array(z.string().max(1024)).max(MAX_PATH_FILTERS).nullable(),
+    blockKey: blockKeySchema,
+    refresh: z.boolean(),
+  }),
+  output: z.custom<ChangesResult>(),
+});
+
+export const projectPatchesRpc = defineRpc({
+  name: "genui.project_patches",
+  input: z.object({
+    agentId: agentIdSchema,
+    target: z.string().max(64).nullable(),
+    paths: z.array(filePath).min(1).max(25),
+  }),
+  output: z.custom<PatchesResult>(),
+});
+
+export const projectCommitsRpc = defineRpc({
+  name: "genui.project_commits",
+  input: z.object({
+    agentId: agentIdSchema,
+    blockKey: blockKeySchema,
+    refresh: z.boolean(),
+  }),
+  output: z.custom<CommitsResult>(),
+});
+
+export const projectPullRequestRpc = defineRpc({
+  name: "genui.project_pull_request",
+  input: z.object({ agentId: agentIdSchema }),
+  output: z.custom<PullRequestResult>(),
+});
+
+export const projectThreadsRpc = defineRpc({
+  name: "genui.project_threads",
+  input: z.object({
+    agentId: agentIdSchema,
+    ids: z.array(z.string().max(128)).max(MAX_THREAD_IDS).nullable(),
+  }),
+  output: z.custom<ThreadsResult>(),
+});
+
+export const projectEnvironmentsRpc = defineRpc({
+  name: "genui.project_environments",
+  input: z.object({ agentId: agentIdSchema }),
+  output: z.custom<EnvironmentsResult>(),
+});
+
+export const projectEnvironmentRpc = defineRpc({
+  name: "genui.project_environment",
+  input: z.object({ agentId: agentIdSchema, environmentId: z.string().min(1).max(128) }),
+  output: z.custom<EnvironmentDetailResult>(),
+});
+
+export const appendDemoRpc = defineRpc({
+  name: "genui.append_demo",
+  input: z.object({
+    agentId: agentIdSchema,
+    component: z.string().max(80).optional(),
+  }),
+  output: z.object({ appended: z.boolean(), name: z.string() }),
+});
+
+export const genuiBlockDataSchema = z.object({
+  language: z.enum(["ui", "app"]),
+  code: z.string(),
+  complete: z.boolean(),
+  fenceIndex: z.number(),
+  messageId: z.string().optional(),
+});
+
+export type GenUiBlockData = z.infer<typeof genuiBlockDataSchema>;
+
+export const genuiTextDataSchema = z.object({
+  text: z.string(),
+  phase: z.enum(["streaming", "complete"]).optional(),
+});
+
+export type GenUiTextData = z.infer<typeof genuiTextDataSchema>;

package/shared/segment.ts

@@ -0,0 +1,81 @@
+import type { PluginTimelineItem } from "@getpaseo/plugin";
+import { findFences } from "./fallback";
+
+export const GENUI_BLOCK_KIND = "genui-block";
+export const GENUI_TEXT_KIND = "genui-text";
+
+export type MessageSegment =
+  | { readonly kind: "text"; readonly text: string }
+  | {
+      readonly kind: "fence";
+      readonly language: "ui" | "app";
+      readonly code: string;
+      readonly complete: boolean;
+      readonly fenceIndex: number;
+    };
+
+export function segmentMessage(text: string, phase: "streaming" | "complete"): MessageSegment[] {
+  const lines = text.split("\n");
+  const allFences = findFences(lines);
+  const uiFences = allFences.filter((fence) => fence.language === "ui" || fence.language === "app");
+  if (uiFences.length === 0) return [{ kind: "text", text }];
+
+  const segments: MessageSegment[] = [];
+  let cursor = 0;
+  let fenceIndex = 0;
+  for (const fence of uiFences) {
+    if (fence.open > cursor) {
+      const prose = lines.slice(cursor, fence.open).join("\n").trim();
+      if (prose !== "") segments.push({ kind: "text", text: prose });
+    }
+    const language = fence.language === "app" ? "app" : "ui";
+    segments.push({
+      kind: "fence",
+      language,
+      code: fence.body,
+      complete: fence.closed,
+      fenceIndex: fenceIndex++,
+    });
+    cursor = fence.close + 1;
+  }
+  if (cursor < lines.length) {
+    const tail = lines.slice(cursor).join("\n").trim();
+    if (tail !== "") segments.push({ kind: "text", text: tail });
+  }
+  return segments;
+}
+
+export function splitTimelineMessage(
+  text: string,
+  phase: "streaming" | "complete",
+  messageId?: string,
+): { items: PluginTimelineItem[] } | undefined {
+  const segments = segmentMessage(text, phase);
+  if (!segments.some((segment) => segment.kind === "fence")) return undefined;
+
+  const items: PluginTimelineItem[] = [];
+  segments.forEach((segment) => {
+    if (segment.kind === "fence") {
+      items.push({
+        type: "plugin",
+        kind: GENUI_BLOCK_KIND,
+        version: 1,
+        data: {
+          language: segment.language,
+          code: segment.code,
+          complete: segment.complete,
+          fenceIndex: segment.fenceIndex,
+          ...(messageId ? { messageId } : {}),
+        },
+      });
+    } else {
+      items.push({
+        type: "plugin",
+        kind: GENUI_TEXT_KIND,
+        version: 1,
+        data: { text: segment.text, phase },
+      });
+    }
+  });
+  return { items };
+}

package/shared/settings.ts

@@ -0,0 +1,12 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const genuiSettings = defineSettings({
+  id: "preferences",
+  scope: "host",
+  version: 1,
+  schema: z.object({
+    autoInstructions: z.boolean().default(true),
+    webLookups: z.boolean().default(true),
+  }),
+});