@cfbender/cesium 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "keywords": [
     "agent",
@@ -24,6 +24,8 @@
   },
   "files": [
     "src",
+    "plugin.lua",
+    "plugin.toml",
     "assets/styleguide.html",
     "agents",
     "ARCHITECTURE.md",

package/plugin.lua

@@ -0,0 +1,197 @@
+-- Hygge Lua plugin entrypoint. Core Cesium behavior remains in TypeScript;
+-- this file only adapts Hygge's Lua plugin API to src/hygge/bridge.ts.
+
+local source = debug.getinfo(1, "S").source
+local plugin_dir = source:sub(1, 1) == "@" and source:sub(2):match("(.+)/[^/]+$") or "."
+local bridge = "src/hygge/bridge.ts"
+
+local function json_escape(value)
+    return value:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t')
+end
+
+local function json_encode(value)
+    local value_type = type(value)
+    if value_type == "nil" then
+        return "null"
+    end
+    if value_type == "boolean" or value_type == "number" then
+        return tostring(value)
+    end
+    if value_type == "string" then
+        return '"' .. json_escape(value) .. '"'
+    end
+    if value_type ~= "table" then
+        error("cannot JSON-encode " .. value_type)
+    end
+
+    local max_index = 0
+    local count = 0
+    for key, _ in pairs(value) do
+        count = count + 1
+        if type(key) == "number" and key > max_index and key % 1 == 0 then
+            max_index = key
+        end
+    end
+
+    if max_index == count then
+        local items = {}
+        for index = 1, max_index do
+            items[index] = json_encode(value[index])
+        end
+        return "[" .. table.concat(items, ",") .. "]"
+    end
+
+    local fields = {}
+    for key, field_value in pairs(value) do
+        fields[#fields + 1] = json_encode(tostring(key)) .. ":" .. json_encode(field_value)
+    end
+    return "{" .. table.concat(fields, ",") .. "}"
+end
+
+local function run_bridge(ctx, name, input)
+    local session_id = (hygge.session and hygge.session.id) or "hygge"
+    local pwd = (ctx and ctx.pwd) or plugin_dir
+    local result = hygge.exec("bun", { "run", bridge, "tool", name, pwd, session_id, "", json_encode(input or {}) }, {
+        dir = plugin_dir,
+        timeout = "10m",
+    })
+
+    if result.code ~= 0 then
+        return { content = result.stderr ~= "" and result.stderr or result.stdout, is_error = true }
+    end
+    return { content = result.stdout }
+end
+
+local string_array = { type = "array", items = { type = "string" } }
+local block_array = { type = "array", items = { type = "object", additionalProperties = true } }
+local question_array = { type = "array", items = { type = "object", additionalProperties = true } }
+
+local tools = {
+	{
+		name = "cesium_publish",
+		description = "Publish a beautiful self-contained HTML document to the cesium artifacts directory.",
+		input_schema = {
+			type = "object",
+			properties = {
+				title = { type = "string" },
+				kind = { type = "string", enum = { "plan", "review", "comparison", "report", "explainer", "design", "audit", "rfc", "other", "ask", "annotate" } },
+				blocks = block_array,
+				summary = { type = "string" },
+				tags = string_array,
+                supersedes = { type = "string" },
+            },
+            required = { "title", "kind", "blocks" },
+            additionalProperties = false,
+        },
+    },
+	{
+		name = "cesium_ask",
+		description = "Publish an interactive Q&A artifact and return its URL.",
+		input_schema = {
+			type = "object",
+			properties = {
+				title = { type = "string" },
+				body = { type = "string" },
+                questions = question_array,
+                summary = { type = "string" },
+                tags = string_array,
+                expiresAt = { type = "string" },
+                requireAll = { type = "boolean" },
+            },
+            required = { "title", "body", "questions" },
+            additionalProperties = false,
+        },
+    },
+	{
+		name = "cesium_annotate",
+		description = "Publish an interactive review artifact with comments and verdict.",
+		input_schema = {
+			type = "object",
+			properties = {
+				title = { type = "string" },
+				blocks = block_array,
+				verdictMode = { type = "string", enum = { "approve", "approve-or-reject", "full" } },
+				perLineFor = string_array,
+				requireVerdict = { type = "boolean" },
+                summary = { type = "string" },
+                tags = string_array,
+                expiresAt = { type = "string" },
+            },
+            required = { "title", "blocks" },
+            additionalProperties = false,
+        },
+    },
+	{
+		name = "cesium_wait",
+		description = "Block until the user completes a cesium_ask or cesium_annotate artifact.",
+		input_schema = {
+			type = "object",
+			properties = {
+				id = { type = "string" },
+                timeoutMs = { type = "number" },
+                pollIntervalMs = { type = "number" },
+            },
+            required = { "id" },
+            additionalProperties = false,
+        },
+    },
+    {
+        name = "cesium_styleguide",
+        description = "Return the Cesium HTML design system reference page.",
+        input_schema = { type = "object", properties = {}, required = {} },
+        parallelizable = true,
+    },
+	{
+		name = "cesium_critique",
+		description = "Analyze a draft Cesium blocks array for design-system adherence.",
+		input_schema = {
+			type = "object",
+			properties = { blocks = block_array },
+			required = { "blocks" },
+			additionalProperties = false,
+        },
+        parallelizable = true,
+    },
+    {
+        name = "cesium_stop",
+        description = "Stop the running Cesium HTTP server.",
+        input_schema = {
+            type = "object",
+            properties = {
+                force = { type = "boolean" },
+                timeoutMs = { type = "number" },
+            },
+            required = { "force", "timeoutMs" },
+            additionalProperties = false,
+        },
+    },
+}
+
+for _, spec in ipairs(tools) do
+    hygge.register_tool {
+        name = spec.name,
+        description = spec.description,
+        input_schema = spec.input_schema,
+        parallelizable = spec.parallelizable,
+        execute = function(ctx, input)
+            return run_bridge(ctx, spec.name, input)
+        end,
+    }
+end
+
+local system_fragment = nil
+
+hygge.register_hook("pre_message", { name = "cesium_system_guidance", timeout = "10s" }, function(event)
+    if system_fragment == nil then
+        local result = hygge.exec("bun", { "run", bridge, "system-fragment" }, { dir = plugin_dir, timeout = "10s" })
+        if result.code ~= 0 or result.stdout == "" then
+            return nil
+        end
+        system_fragment = result.stdout
+    end
+
+	return {
+		decision = "allow",
+		system_prompt_append = system_fragment,
+	}
+end)

package/plugin.toml

@@ -0,0 +1,4 @@
+name = "cesium"
+version = "0.8.0"
+description = "Beautiful self-contained HTML artifacts for Hygge agents"
+entrypoint = "plugin.lua"

package/src/hygge/bridge.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env bun
+
+// Hygge adapter boundary: execute Cesium's existing TypeScript tool handlers from Lua.
+
+import { $ } from "bun";
+import { dirname, join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type { PluginInput } from "@opencode-ai/plugin";
+import { createPublishTool } from "../tools/publish.ts";
+import { createAskTool } from "../tools/ask.ts";
+import { createAnnotateTool } from "../tools/annotate.ts";
+import { createWaitTool } from "../tools/wait.ts";
+import { createStyleguideTool } from "../tools/styleguide.ts";
+import { createCritiqueTool } from "../tools/critique.ts";
+import { createStopTool } from "../tools/stop.ts";
+import { generateBlockFieldReference } from "../prompt/field-reference.ts";
+import { recordSessionModel } from "../session-model.ts";
+
+type ToolName =
+  | "cesium_publish"
+  | "cesium_ask"
+  | "cesium_annotate"
+  | "cesium_wait"
+  | "cesium_styleguide"
+  | "cesium_critique"
+  | "cesium_stop";
+
+interface ExecutableTool {
+  execute: (args: Record<string, unknown>, context: unknown) => unknown | Promise<unknown>;
+}
+
+const toolNames = new Set<ToolName>([
+  "cesium_publish",
+  "cesium_ask",
+  "cesium_annotate",
+  "cesium_wait",
+  "cesium_styleguide",
+  "cesium_critique",
+  "cesium_stop",
+]);
+
+function isToolName(value: string): value is ToolName {
+  return toolNames.has(value as ToolName);
+}
+
+async function readStdin(): Promise<string> {
+  return await Bun.stdin.text();
+}
+
+function makeContext(directory: string): PluginInput {
+  const ctx = {
+    directory,
+    worktree: "",
+    $,
+    client: {},
+    project: {},
+    experimental_workspace: {},
+    serverUrl: "",
+  };
+  return ctx as unknown as PluginInput;
+}
+
+function createTool(name: ToolName, ctx: PluginInput): ExecutableTool {
+  const tool = (() => {
+    switch (name) {
+      case "cesium_publish":
+        return createPublishTool(ctx);
+      case "cesium_ask":
+        return createAskTool(ctx);
+      case "cesium_annotate":
+        return createAnnotateTool(ctx);
+      case "cesium_wait":
+        return createWaitTool(ctx);
+      case "cesium_styleguide":
+        return createStyleguideTool(ctx);
+      case "cesium_critique":
+        return createCritiqueTool(ctx);
+      case "cesium_stop":
+        return createStopTool(ctx);
+    }
+  })();
+
+  return tool as unknown as ExecutableTool;
+}
+
+async function systemFragment(): Promise<string> {
+  const root = dirname(dirname(fileURLToPath(import.meta.url)));
+  const raw = await readFile(join(root, "prompt/system-fragment.md"), "utf8");
+  return raw.replace("{{BLOCK_FIELD_REFERENCE}}", generateBlockFieldReference());
+}
+
+async function main(): Promise<void> {
+  const command = process.argv[2];
+  if (command === "system-fragment") {
+    process.stdout.write(await systemFragment());
+    return;
+  }
+
+  if (command !== "tool") {
+    throw new Error("usage: bridge.ts system-fragment | tool <name> [cwd] [sessionID] [model] [json]");
+  }
+
+  const name = process.argv[3];
+  if (name === undefined || !isToolName(name)) {
+    throw new Error(`unknown Cesium tool: ${name ?? "<missing>"}`);
+  }
+
+  const directory = process.argv[4] ?? process.cwd();
+  const sessionID = process.argv[5] ?? "hygge";
+  const model = process.argv[6];
+  if (model !== undefined && model.length > 0) {
+    recordSessionModel(sessionID, "hygge", model);
+  }
+
+  const rawInput = process.argv[7] ?? (await readStdin());
+  const parsedInput: unknown = rawInput.trim().length === 0 ? {} : JSON.parse(rawInput);
+  if (typeof parsedInput !== "object" || parsedInput === null || Array.isArray(parsedInput)) {
+    throw new Error("tool input must be a JSON object");
+  }
+
+  const args = parsedInput as Record<string, unknown>;
+  const result = await createTool(name, makeContext(directory)).execute(args, { sessionID });
+  process.stdout.write(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+}
+
+try {
+  await main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/src/render/client-js.ts

@@ -896,12 +896,21 @@ export function getClientJs(): string {
 
         menu.hidden = false;
         var menuRect = menu.getBoundingClientRect();
-        var top = rect.bottom + window.scrollY + 6;
-        var left = rect.right + window.scrollX - menuRect.width;
+        // The menu uses position: fixed, so coordinates are viewport-relative —
+        // do NOT add window.scrollX/scrollY here, or the menu gets parked at
+        // (rect + scrollY) which is off-screen as soon as the user scrolls.
+        var top = rect.bottom + 6;
+        var left = rect.right - menuRect.width;
         // Clamp to viewport
         var vpW = window.innerWidth || document.documentElement.clientWidth;
+        var vpH = window.innerHeight || document.documentElement.clientHeight;
         if (left + menuRect.width > vpW - 8) left = vpW - menuRect.width - 8;
         if (left < 8) left = 8;
+        // If the menu would fall below the viewport, flip above the selection.
+        if (top + menuRect.height > vpH - 8) {
+          top = rect.top - menuRect.height - 6;
+        }
+        if (top < 8) top = 8;
         menu.style.top = top + "px";
         menu.style.left = left + "px";
 

package/src/render/theme.ts

@@ -1134,14 +1134,24 @@ body { position: relative; }
   z-index: 50;
 }
 /* When annotate is active and viewport has room for page + rail side-by-side,
-   shift .page leftward so its right edge (and the .cs-anchor-affordance-block
-   button parked at right: 8px of each annotatable block) does not slide under
-   the rail. Required viewport width: 1120 (page) + 24 (gap) + 280 (rail) +
-   24 (right gutter) = 1448px. */
+   shift the content area leftward so its right edge (and the
+   .cs-anchor-affordance-block button parked at right: 8px of each annotatable
+   block) does not slide under the rail.
+
+   Artifacts have no .page wrapper — content sits directly in <body>. So we
+   shrink the body content via padding-right. The legacy .page rule remains so
+   the same shift works on index pages.
+
+   Required viewport width: 1120 (page) + 24 (gap) + 280 (rail) + 24 (right
+   gutter) = 1448px. */
 @media (min-width: 1448px) {
+  body.cs-annotate-active,
+  body:has(.cs-annotate-scaffold) {
+    padding-right: 328px; /* rail width (280) + outer gutter (24) + inner gap (24) */
+  }
   body.cs-annotate-active .page,
   body:has(.cs-annotate-scaffold) .page {
-    margin-right: 328px; /* rail width (280) + outer gutter (24) + inner gap (24) */
+    margin-right: 0;
     margin-left: auto;
   }
 }