ocuclaw 1.2.4 → 1.3.0

package/dist/tools/glasses-ui-descriptors.js

@@ -0,0 +1,261 @@
+// Kind-descriptor registry for the glasses-UI surface kinds. Each descriptor
+// is a self-contained unit owning everything per-kind on the PLUGIN side:
+//   - schemaBranch:   the JSON-Schema oneOf entry for this kind
+//   - validateSpec:   per-kind validation, returns the canonical
+//                     { ok:true, spec } | { ok:false, code, message } shape
+//   - refreshTargets: which refresh.targets fields this kind binds
+//                     ("body" for text, "items" for the list kinds) —
+//                     informational in Phase 1, consumed in Phase 3.
+// The core (glassesUiParametersSchema, validateGlassesUiSpec) dispatches by
+// kind STRING through this registry and never switches on a specific kind, so
+// adding a kind is one descriptor with zero core edits (spec §Modularity).
+// Phase 1 ports the existing 3 kinds with NO behavior change.
+//
+// NOTE: this module imports GLASSES_UI_LIMITS from ./glasses-ui-limits.js (a
+// dependency-free leaf), NOT from ./glasses-ui-tool.js — glasses-ui-tool.js
+// imports THIS module, so importing back from it would form a require cycle
+// that the CJS emitter cannot resolve (module.exports is written at
+// end-of-module, so a mid-cycle require sees {}). See glasses-ui-limits.ts.
+
+import { GLASSES_UI_LIMITS } from "./glasses-ui-limits.js";
+
+// Shared title validation (moved from validateGlassesUiSpec — every kind ran
+// it before its branch). Returns an error result or null.
+function validateTitle(obj) {
+  if (typeof obj.title === "undefined") return null;
+  if (typeof obj.title !== "string") {
+    return { ok: false, code: "title_too_long", message: "title must be a string" };
+  }
+  if (obj.title.length > GLASSES_UI_LIMITS.titleMax) {
+    return {
+      ok: false,
+      code: "title_too_long",
+      message: `title is ${obj.title.length} chars; max ${GLASSES_UI_LIMITS.titleMax}`,
+    };
+  }
+  return null;
+}
+
+// ---- text_surface ------------------------------------------------------
+const textSurfaceDescriptor = {
+  kind: "text_surface",
+  refreshTargets: ["body"],
+  schemaBranch: {
+    title: "text_surface",
+    type: "object",
+    required: ["kind", "body"],
+    properties: {
+      kind: { const: "text_surface" },
+      title: { type: "string", maxLength: GLASSES_UI_LIMITS.titleMax },
+      body: { type: "string", maxLength: GLASSES_UI_LIMITS.bodyMax },
+      refresh: undefined, // filled by the tool when assembling the schema
+    },
+  },
+  validateSpec(obj) {
+    const titleErr = validateTitle(obj);
+    if (titleErr) return titleErr;
+    const body = obj.body;
+    if (typeof body !== "string") {
+      return { ok: false, code: "missing_field", message: "text_surface requires body (string)" };
+    }
+    if (body.length > GLASSES_UI_LIMITS.bodyMax) {
+      return {
+        ok: false,
+        code: "body_too_long",
+        message: `body is ${body.length} chars; max ${GLASSES_UI_LIMITS.bodyMax}`,
+      };
+    }
+    const spec = { kind: "text_surface", body };
+    if (typeof obj.title === "string") spec.title = obj.title;
+    return { ok: true, spec };
+  },
+};
+
+// ---- list_surface ------------------------------------------------------
+const listSurfaceDescriptor = {
+  kind: "list_surface",
+  refreshTargets: ["items"],
+  schemaBranch: {
+    title: "list_surface",
+    type: "object",
+    required: ["kind", "items"],
+    properties: {
+      kind: { const: "list_surface" },
+      title: { type: "string", maxLength: GLASSES_UI_LIMITS.titleMax },
+      items: {
+        type: "array",
+        minItems: 1,
+        maxItems: GLASSES_UI_LIMITS.maxItems,
+        items: { type: "string", maxLength: GLASSES_UI_LIMITS.itemMax },
+      },
+      refresh: undefined,
+    },
+  },
+  validateSpec(obj) {
+    const titleErr = validateTitle(obj);
+    if (titleErr) return titleErr;
+    const items = obj.items;
+    if (!Array.isArray(items) || items.length === 0) {
+      return { ok: false, code: "missing_field", message: "list_surface requires items (non-empty array)" };
+    }
+    if (items.length > GLASSES_UI_LIMITS.maxItems) {
+      return {
+        ok: false,
+        code: "too_many_items",
+        message: `${items.length} items; max ${GLASSES_UI_LIMITS.maxItems}`,
+      };
+    }
+    for (let i = 0; i < items.length; i += 1) {
+      const item = items[i];
+      if (typeof item !== "string") {
+        return { ok: false, code: "item_too_long", message: `items[${i}] must be a string` };
+      }
+      if (item.length > GLASSES_UI_LIMITS.itemMax) {
+        return {
+          ok: false,
+          code: "item_too_long",
+          message: `items[${i}] is ${item.length} chars; max ${GLASSES_UI_LIMITS.itemMax}`,
+        };
+      }
+    }
+    const spec = { kind: "list_surface", items };
+    if (typeof obj.title === "string") spec.title = obj.title;
+    return { ok: true, spec };
+  },
+};
+
+// ---- list_with_details_surface ----------------------------------------
+const listWithDetailsSurfaceDescriptor = {
+  kind: "list_with_details_surface",
+  refreshTargets: ["items"],
+  schemaBranch: {
+    title: "list_with_details_surface",
+    type: "object",
+    required: ["kind", "items"],
+    properties: {
+      kind: { const: "list_with_details_surface" },
+      title: { type: "string", maxLength: GLASSES_UI_LIMITS.titleMax },
+      items: {
+        type: "array",
+        minItems: 1,
+        maxItems: GLASSES_UI_LIMITS.maxItems,
+        items: {
+          type: "object",
+          required: ["label"],
+          properties: {
+            label: { type: "string", maxLength: GLASSES_UI_LIMITS.itemMax },
+            body: { type: "string", maxLength: GLASSES_UI_LIMITS.detailBodyMax },
+          },
+        },
+      },
+      refresh: undefined,
+    },
+  },
+  validateSpec(obj) {
+    const titleErr = validateTitle(obj);
+    if (titleErr) return titleErr;
+    // Empirically (2026-05-24 hardware logs), the agent often produces the
+    // parallel-array shape — items=[strings] plus a sibling `details` /
+    // `itemDetails` / `bodies` array — instead of the canonical [{label, body?}]
+    // objects. We accept the parallel-array shape and coerce it server-side so
+    // the wire format downstream stays canonical.
+    const rawItems = obj.items;
+    if (!Array.isArray(rawItems) || rawItems.length === 0) {
+      return {
+        ok: false,
+        code: "missing_field",
+        message: "list_with_details_surface requires items (non-empty array)",
+      };
+    }
+    if (rawItems.length > GLASSES_UI_LIMITS.maxItems) {
+      return {
+        ok: false,
+        code: "too_many_items",
+        message: `${rawItems.length} items; max ${GLASSES_UI_LIMITS.maxItems}`,
+      };
+    }
+    const parallelBodies =
+      Array.isArray(obj.details) ? obj.details
+      : Array.isArray(obj.itemDetails) ? obj.itemDetails
+      : Array.isArray(obj.bodies) ? obj.bodies
+      : null;
+    const items = rawItems.map((entry, i) => {
+      if (typeof entry === "string") {
+        const sibling = parallelBodies ? parallelBodies[i] : undefined;
+        // The sibling can be a plain string body, OR (some models do this) a
+        // {label, body} object that duplicates the label — accept either.
+        if (typeof sibling === "string") {
+          return { label: entry, body: sibling };
+        }
+        if (sibling && typeof sibling === "object" && typeof sibling.body === "string") {
+          return { label: entry, body: sibling.body };
+        }
+        // No matching parallel body — degrade gracefully to label-only.
+        return { label: entry };
+      }
+      return entry;
+    });
+    let totalBodyChars = 0;
+    const normalizedItems = [];
+    for (let i = 0; i < items.length; i += 1) {
+      const it = items[i];
+      if (!it || typeof it !== "object") {
+        return { ok: false, code: "missing_field", message: `items[${i}] must be an object {label, body?}` };
+      }
+      if (typeof it.label !== "string") {
+        return { ok: false, code: "missing_field", message: `items[${i}].label is required` };
+      }
+      if (it.label.length > GLASSES_UI_LIMITS.itemMax) {
+        return {
+          ok: false,
+          code: "item_too_long",
+          message: `items[${i}].label is ${it.label.length} chars; max ${GLASSES_UI_LIMITS.itemMax}`,
+        };
+      }
+      const normalized = { label: it.label };
+      if (it.body !== undefined) {
+        if (typeof it.body !== "string") {
+          return { ok: false, code: "detail_body_too_long", message: `items[${i}].body must be a string` };
+        }
+        if (it.body.length > GLASSES_UI_LIMITS.detailBodyMax) {
+          return {
+            ok: false,
+            code: "detail_body_too_long",
+            message: `items[${i}].body is ${it.body.length} chars; max ${GLASSES_UI_LIMITS.detailBodyMax}`,
+          };
+        }
+        totalBodyChars += it.body.length;
+        normalized.body = it.body;
+      }
+      normalizedItems.push(normalized);
+    }
+    if (totalBodyChars > GLASSES_UI_LIMITS.totalDetailPayloadMax) {
+      return {
+        ok: false,
+        code: "total_payload_too_large",
+        message: `bodies sum to ${totalBodyChars} chars; max ${GLASSES_UI_LIMITS.totalDetailPayloadMax}`,
+      };
+    }
+    const spec = { kind: "list_with_details_surface", items: normalizedItems };
+    if (typeof obj.title === "string") spec.title = obj.title;
+    return { ok: true, spec };
+  },
+};
+
+export const GLASSES_UI_KIND_DESCRIPTORS = [
+  textSurfaceDescriptor,
+  listSurfaceDescriptor,
+  listWithDetailsSurfaceDescriptor,
+];
+
+export function getKindDescriptor(kind) {
+  return GLASSES_UI_KIND_DESCRIPTORS.find((d) => d.kind === kind);
+}
+
+export function listKindStrings() {
+  return GLASSES_UI_KIND_DESCRIPTORS.map((d) => d.kind);
+}
+
+export function buildOneOfBranches() {
+  return GLASSES_UI_KIND_DESCRIPTORS.map((d) => d.schemaBranch);
+}

package/dist/tools/glasses-ui-limits.js

@@ -0,0 +1,21 @@
+// Shared per-kind size caps for the glasses-UI surface tool. Extracted into its
+// own leaf module so BOTH the tool (glasses-ui-tool.ts) and the kind-descriptor
+// registry (glasses-ui-descriptors.ts) can import the same limits WITHOUT
+// forming an import cycle between those two modules.
+//
+// Why a leaf module is required (not a cycle): the plugin's CJS emitter
+// (scripts/build.mjs) converts `import {X} from "y"` into an in-place
+// `const {X} = require("y.cjs")` and appends `module.exports = {...}` only at
+// END of module execution (no live getters). Under those semantics a
+// bidirectional descriptors<->tool require resolves to `{}` mid-cycle and
+// crashes (GLASSES_UI_LIMITS undefined / listKindStrings not a function). Giving
+// the limits their own dependency-free module makes the graph a DAG
+// (tool -> {limits, descriptors}; descriptors -> limits), so no cycle exists.
+export const GLASSES_UI_LIMITS = {
+  bodyMax: 1000,
+  itemMax: 64,
+  titleMax: 64,
+  maxItems: 20,
+  detailBodyMax: 200,
+  totalDetailPayloadMax: 6 * 1024,
+};

package/dist/tools/glasses-ui-paint-floor.js

@@ -0,0 +1,99 @@
+// Per-surface trailing-edge paint-floor coalescer.
+//
+// Governs ALL plugin->glass sends (initial RebuildPageContainer render and
+// every surface_update patch). Collapses bursts to last-write-wins per field
+// and emits at most one frame per paintFloorMs (default 150ms, Spike D), with
+// a leading-edge send + a trailing send carrying the final merged patch.
+//
+// There is NO glass-side paint-ack: the only backpressure signal is
+// relay/BLE transport-side (see the isUnderBackpressure shed in Task 13).
+// Local fake-list textContainerUpgrade scroll-swaps are client-side and never
+// reach this coalescer.
+
+export const DEFAULT_PAINT_FLOOR_MS = 150;
+
+export function createPaintFloorCoalescer(deps) {
+  const paintFloorMs = Number.isFinite(deps.paintFloorMs) ? deps.paintFloorMs : DEFAULT_PAINT_FLOOR_MS;
+  const send = deps.send;
+  const nowMs = typeof deps.nowMs === "function" ? deps.nowMs : () => performance.now();
+  const setTimeoutFn = deps.setTimeoutFn || setTimeout;
+  const clearTimeoutFn = deps.clearTimeoutFn || clearTimeout;
+  const isUnderBackpressure =
+    typeof deps.isUnderBackpressure === "function" ? deps.isUnderBackpressure : () => false;
+
+  // surfaceId -> { sessionKey, lastSentAt, pendingPatch, timer }
+  const bySurface = new Map();
+
+  function isRenderSentinel(p) {
+    return !!(p && p.__render === true);
+  }
+
+  function mergePatch(base, incoming) {
+    // A render sentinel ({ __render, __depth, __spec }, Task 13) and a field
+    // patch ({ body }/{ items }/{ title }) must NEVER shallow-merge — a merged
+    // object would carry both __spec and a stray `body`, painting a malformed
+    // frame. They are different write kinds, so the LATER write supersedes the
+    // earlier one wholesale (a render replaces a queued field patch; a field
+    // patch after a queued render replaces that render). Same-kind writes
+    // merge last-write-wins per field as before.
+    if (isRenderSentinel(base) !== isRenderSentinel(incoming)) {
+      return incoming && typeof incoming === "object" ? { ...incoming } : {};
+    }
+    const merged = base ? { ...base } : {};
+    if (incoming && typeof incoming === "object") {
+      for (const k of Object.keys(incoming)) merged[k] = incoming[k];
+    }
+    return merged;
+  }
+
+  function flush(surfaceId) {
+    const st = bySurface.get(surfaceId);
+    if (!st || !st.pendingPatch) return;
+    st.timer = null;
+    if (isUnderBackpressure()) {
+      // Shed: do NOT send while the relay/BLE send buffer is over the high
+      // water mark. Retain pendingPatch (last-write-wins) and re-arm so the
+      // final merged value lands once pressure clears. No glass-side ack
+      // exists, so transport-side pressure is the only signal.
+      st.timer = setTimeoutFn(() => flush(surfaceId), Math.max(16, paintFloorMs));
+      return;
+    }
+    const patch = st.pendingPatch;
+    st.pendingPatch = null;
+    st.lastSentAt = nowMs();
+    send({ surfaceId, sessionKey: st.sessionKey, patch });
+  }
+
+  function enqueue(params) {
+    const { surfaceId, sessionKey, patch } = params;
+    let st = bySurface.get(surfaceId);
+    if (!st) {
+      st = { sessionKey, lastSentAt: -Infinity, pendingPatch: null, timer: null };
+      bySurface.set(surfaceId, st);
+    }
+    st.sessionKey = sessionKey;
+    const elapsed = nowMs() - st.lastSentAt;
+    if (elapsed >= paintFloorMs && !st.timer) {
+      // Leading edge: send immediately.
+      st.lastSentAt = nowMs();
+      send({ surfaceId, sessionKey, patch });
+      return;
+    }
+    // Within the floor: merge into the pending patch, arm a trailing flush.
+    st.pendingPatch = mergePatch(st.pendingPatch, patch);
+    if (!st.timer) {
+      const wait = Math.max(0, paintFloorMs - elapsed);
+      st.timer = setTimeoutFn(() => flush(surfaceId), wait);
+    }
+  }
+
+  function dispose(surfaceId) {
+    const st = bySurface.get(surfaceId);
+    if (st && st.timer) clearTimeoutFn(st.timer);
+    bySurface.delete(surfaceId);
+  }
+
+  return { enqueue, dispose, _bySurface: bySurface };
+}
+
+export default { createPaintFloorCoalescer, DEFAULT_PAINT_FLOOR_MS };