@jackwener/opencli 1.7.22 → 1.8.1

package/clis/geogebra/geogebra.test.js

@@ -0,0 +1,175 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ensureApplet, ggbEval, ggbGetProperty, ggbListObjects, ggbWaitForObjectCount } from './utils.js';
+import './add-circle.js';
+import './add-line.js';
+import './add-point.js';
+import './add-polygon.js';
+import './eval.js';
+import './hexagon.js';
+import './info.js';
+import './list.js';
+import './triangle.js';
+
+function createPageMock(url = 'https://www.geogebra.org/geometry') {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(),
+    getCurrentUrl: vi.fn().mockResolvedValue(url),
+    wait: vi.fn().mockResolvedValue(undefined),
+    screenshot: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('ensureApplet', () => {
+  it('skips navigation when already on the geometry page', async () => {
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate.mockResolvedValue(true);
+    await ensureApplet(page);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('unwraps Browser Bridge evaluate envelopes while checking applet readiness', async () => {
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate.mockResolvedValue({ session: 1, data: true });
+    await ensureApplet(page);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('navigates when not on the geometry page', async () => {
+    const page = createPageMock('https://example.com');
+    page.evaluate.mockResolvedValue(true);
+    await ensureApplet(page);
+    expect(page.goto).toHaveBeenCalledWith('https://www.geogebra.org/geometry');
+  });
+
+  it('throws when ggbApplet never becomes available', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue(false);
+    await expect(ensureApplet(page)).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbEval', () => {
+  it('calls evalCommandGetLabels and evalCommand', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ ok: true, label: 'A', beforeCount: 0, afterCount: 1, error: null });
+    const result = await ggbEval(page, 'A=(1,2)');
+    expect(result).toEqual({ ok: true, label: 'A', beforeCount: 0, afterCount: 1, error: null });
+    expect(page.evaluate).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws typed errors for malformed evaluate results', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ nope: true });
+    await expect(ggbEval(page, 'A=(1,2)')).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbGetProperty', () => {
+  it('requests a property from the applet', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue('point');
+    const result = await ggbGetProperty(page, 'A', 'type');
+    expect(result).toBe('point');
+  });
+});
+
+describe('ggbListObjects', () => {
+  it('normalizes object rows from the applet', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue([
+      { name: 'A', type: 'point', value: '(0, 0)', visible: true },
+      { name: 't1', type: 'polygon', value: '', visible: true },
+    ]);
+    const result = await ggbListObjects(page);
+    expect(result).toHaveLength(2);
+    expect(page.evaluate).toHaveBeenCalledTimes(1);
+  });
+
+  it('unwraps Browser Bridge envelopes for object rows', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ session: 1, data: [{ name: 'A', type: 'point', value: '(0, 0)', visible: true }] });
+    const result = await ggbListObjects(page);
+    expect(result).toEqual([{ name: 'A', type: 'point', value: '(0, 0)', visible: true }]);
+  });
+
+  it('throws typed error when object names exist but property extraction fails', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue({ error: 'getObjectType failed', name: 'A' });
+    await expect(ggbListObjects(page)).rejects.toThrow(CommandExecutionError);
+  });
+});
+
+describe('ggbWaitForObjectCount', () => {
+  it('returns the detected object count', async () => {
+    const page = createPageMock();
+    page.evaluate.mockResolvedValue(4);
+    const result = await ggbWaitForObjectCount(page, 4);
+    expect(result).toBe(4);
+  });
+});
+
+describe('geogebra command typed boundaries', () => {
+  it('validates add-point args before navigating', async () => {
+    const command = getRegistry().get('geogebra/add-point');
+    const page = createPageMock('https://example.com');
+    await expect(command.func(page, { name: 'A', coords: 'bad' })).rejects.toThrow(ArgumentError);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('validates triangle size before navigating instead of silently defaulting', async () => {
+    const command = getRegistry().get('geogebra/triangle');
+    const page = createPageMock('https://example.com');
+    await expect(command.func(page, { size: 'not-a-number' })).rejects.toThrow(ArgumentError);
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('fails eval command execution instead of returning a success row for failed commands', async () => {
+    const command = getRegistry().get('geogebra/eval');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: false, label: '', beforeCount: 0, afterCount: 0, error: 'Unknown command' });
+    await expect(command.func(page, { command: 'NotACommand(' })).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('creates add-line rows from validated labels', async () => {
+    const command = getRegistry().get('geogebra/add-line');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: true, label: 'f', beforeCount: 2, afterCount: 3, error: null });
+    await expect(command.func(page, { points: 'A,B', type: 'segment' })).resolves.toEqual([
+      { label: 'f', type: 'segment', points: 'A,B' },
+    ]);
+  });
+
+  it('does not turn object property extraction failures into empty list results', async () => {
+    const command = getRegistry().get('geogebra/list');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ error: 'getObjectType failed', name: 'A' });
+    await expect(command.func(page, {})).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('does not turn malformed info existence probes into not-found results', async () => {
+    const command = getRegistry().get('geogebra/info');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ nope: true });
+    await expect(command.func(page, { name: 'A' })).rejects.toThrow(CommandExecutionError);
+  });
+
+  it('maps explicit false info existence probes to EmptyResultError', async () => {
+    const command = getRegistry().get('geogebra/info');
+    const page = createPageMock('https://www.geogebra.org/geometry');
+    page.evaluate
+      .mockResolvedValueOnce(true)
+      .mockResolvedValueOnce({ ok: true, exists: false });
+    await expect(command.func(page, { name: 'A' })).rejects.toThrow(EmptyResultError);
+  });
+});

package/clis/geogebra/hexagon.js

@@ -0,0 +1,62 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureApplet, ggbEval, ggbListObjects, ggbWaitForObjectCount, normalizeNumber, requireGgbSuccess } from './utils.js';
+
+/**
+ * Draw a regular hexagon on the GeoGebra Geometry canvas.
+ * Creates center point, vertex, and the regular polygon in one session.
+ */
+cli({
+  site: 'geogebra',
+  name: 'hexagon',
+  access: 'write',
+  description: 'Draw a regular hexagon centered at the origin',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra hexagon --size 3',
+  args: [
+    { name: 'size', required: false, default: '2', help: 'Radius of the hexagon (default: 2)' },
+  ],
+  columns: ['step', 'result'],
+  func: async (page, kwargs) => {
+    const size = normalizeNumber(kwargs.size, 'size', { defaultValue: 2, positive: true });
+    await ensureApplet(page);
+    const results = [];
+
+    const vertices = [
+      ['V1', `(${size},0)`],
+      ['V2', `(${size}*cos(pi/3),${size}*sin(pi/3))`],
+      ['V3', `(${size}*cos(2*pi/3),${size}*sin(2*pi/3))`],
+      ['V4', `(-${size},0)`],
+      ['V5', `(${size}*cos(4*pi/3),${size}*sin(4*pi/3))`],
+      ['V6', `(${size}*cos(5*pi/3),${size}*sin(5*pi/3))`],
+    ];
+    for (const [name, coords] of vertices) {
+      const result = requireGgbSuccess(await ggbEval(page, `${name}=${coords}`), `Failed to create point ${name}`);
+      results.push({ step: `${name}=${coords}`, result: `ok (${result.label || name})` });
+    }
+
+    const polygon = requireGgbSuccess(await ggbEval(page, 'Hexagon=Polygon(V1,V2,V3,V4,V5,V6)'), 'Failed to create hexagon polygon');
+    results.push({ step: 'Hexagon=Polygon(V1,V2,V3,V4,V5,V6)', result: `ok (${polygon.label || 'hexagon created'})` });
+
+    const objectCount = await ggbWaitForObjectCount(page, 7);
+    const objects = await ggbListObjects(page);
+    const screenshotPath = path.join(os.tmpdir(), 'opencli-geogebra-hexagon.png');
+    try {
+      await page.screenshot({ path: screenshotPath });
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to capture GeoGebra screenshot: ${err?.message || err}`);
+    }
+
+    if (Array.isArray(objects) && objects.length > 0) {
+      results.push({ step: `canvas has ${objectCount} objects`, result: objects.map(o => `${o.name}(${o.type})`).join(', ') });
+    }
+    results.push({ step: 'screenshot', result: screenshotPath });
+
+    return results;
+  },
+});

package/clis/geogebra/info.js

@@ -0,0 +1,72 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbGetProperty, normalizeLabel, unwrapBridgeEnvelope } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'info',
+  access: 'read',
+  description: 'Get detailed properties of a GeoGebra object',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra info --name A',
+  args: [
+    { name: 'name', required: true, help: 'Object label (e.g. A, c1, poly1)' },
+  ],
+  columns: ['property', 'value'],
+  func: async (page, kwargs) => {
+    const objName = normalizeLabel(kwargs.name, 'name');
+    await ensureApplet(page);
+
+    let exists;
+    try {
+      exists = unwrapBridgeEnvelope(await page.evaluate(`
+        (name => {
+          try {
+            if (typeof ggbApplet === 'undefined' || typeof ggbApplet.getObjectType !== 'function') {
+              return { error: 'ggbApplet is not ready' };
+            }
+            return { ok: true, exists: ggbApplet.getObjectType(name) !== '' };
+          } catch (err) {
+            return { error: err?.message || String(err) };
+          }
+        })
+        (${JSON.stringify(objName)})
+      `));
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to inspect GeoGebra object: ${err?.message || err}`);
+    }
+    if (!exists || typeof exists !== 'object' || Array.isArray(exists)) {
+      throw new CommandExecutionError('GeoGebra object existence probe returned malformed result');
+    }
+    if (exists.error) {
+      throw new CommandExecutionError(`Failed to inspect GeoGebra object: ${exists.error}`);
+    }
+    if (exists.ok !== true || typeof exists.exists !== 'boolean') {
+      throw new CommandExecutionError('GeoGebra object existence probe returned malformed result');
+    }
+    if (exists.exists === false) {
+      throw new EmptyResultError(`geogebra info ${objName}`, `Object "${objName}" not found on the canvas.`);
+    }
+
+    const properties = ['type', 'value', 'definition', 'command', 'caption', 'visible', 'color'];
+    const rows = [];
+    for (const prop of properties) {
+      const val = await ggbGetProperty(page, objName, prop);
+      rows.push({ property: prop, value: String(val ?? '') });
+    }
+
+    // For point-like objects, also include coordinates
+    const objType = await ggbGetProperty(page, objName, 'type');
+    if (objType === 'point') {
+      const x = await ggbGetProperty(page, objName, 'xcoord');
+      const y = await ggbGetProperty(page, objName, 'ycoord');
+      rows.push({ property: 'x', value: String(x ?? '') });
+      rows.push({ property: 'y', value: String(y ?? '') });
+    }
+
+    return rows;
+  },
+});

package/clis/geogebra/list.js

@@ -0,0 +1,35 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ensureApplet, ggbListObjects } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'list',
+  access: 'read',
+  description: 'List all geometric objects on the GeoGebra canvas',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  args: [
+    { name: 'type', required: false, help: 'Filter by object type (e.g. "point", "line", "circle")' },
+  ],
+  columns: ['name', 'type', 'value', 'visible'],
+  func: async (page, kwargs) => {
+    const filterType = kwargs.type == null || kwargs.type === ''
+      ? ''
+      : String(kwargs.type).trim().toLowerCase();
+    if (filterType && !/^[a-z-]+$/.test(filterType)) {
+      throw new ArgumentError('type must be a GeoGebra object type like point, line, or circle');
+    }
+    await ensureApplet(page);
+    const objects = await ggbListObjects(page, filterType);
+    if (!Array.isArray(objects) || objects.length === 0) {
+      throw new EmptyResultError(
+        'geogebra list',
+        'No objects found on the canvas. Fresh runs start a blank session; use one "eval" call, or inspect an already-bound tab through the browser workspace commands.',
+      );
+    }
+    return objects;
+  },
+});

package/clis/geogebra/triangle.js

@@ -0,0 +1,60 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import os from 'node:os';
+import path from 'node:path';
+import { ensureApplet, ggbEval, ggbListObjects, ggbWaitForObjectCount, normalizeNumber, requireGgbSuccess } from './utils.js';
+
+cli({
+  site: 'geogebra',
+  name: 'triangle',
+  access: 'write',
+  description: 'Draw an equilateral triangle from a horizontal base segment',
+  domain: 'www.geogebra.org',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  navigateBefore: false,
+  example: 'opencli geogebra triangle --size 4',
+  args: [
+    { name: 'size', required: false, default: '2', help: 'Side length of the triangle (default: 2)' },
+  ],
+  columns: ['step', 'result'],
+  func: async (page, kwargs) => {
+    const size = normalizeNumber(kwargs.size, 'size', { defaultValue: 2, positive: true });
+    await ensureApplet(page);
+    const results = [];
+
+    const r1 = requireGgbSuccess(await ggbEval(page, 'A=(0,0)'), 'Failed to create point A');
+    results.push({ step: 'base point A=(0,0)', result: `ok (${r1.label || 'A'})` });
+
+    const r2 = requireGgbSuccess(await ggbEval(page, `B=(${size},0)`), 'Failed to create point B');
+    results.push({ step: `base point B=(${size},0)`, result: `ok (${r2.label || 'B'})` });
+
+    const r3 = requireGgbSuccess(await ggbEval(page, 'c=Circle(A,B)'), 'Failed to create circle c');
+    results.push({ step: 'c=Circle(A,B)', result: `ok (${r3.label || 'c'})` });
+
+    const r4 = requireGgbSuccess(await ggbEval(page, 'd=Circle(B,A)'), 'Failed to create circle d');
+    results.push({ step: 'd=Circle(B,A)', result: `ok (${r4.label || 'd'})` });
+
+    const r5 = requireGgbSuccess(await ggbEval(page, 'C=Intersect(c,d,1)'), 'Failed to create point C');
+    results.push({ step: 'C=Intersect(c,d,1)', result: `ok (${r5.label || 'C'})` });
+
+    const r6 = requireGgbSuccess(await ggbEval(page, 'Polygon(A,B,C)'), 'Failed to create triangle polygon');
+    results.push({ step: 'Polygon(A,B,C)', result: `ok (${r6.label || 'triangle created'})` });
+
+    const objectCount = await ggbWaitForObjectCount(page, 5);
+    const objects = await ggbListObjects(page);
+    const screenshotPath = path.join(os.tmpdir(), 'opencli-geogebra-triangle.png');
+    try {
+      await page.screenshot({ path: screenshotPath });
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to capture GeoGebra screenshot: ${err?.message || err}`);
+    }
+    results.push({
+      step: `canvas has ${objectCount} objects`,
+      result: objects.map((obj) => `${obj.name}(${obj.type})`).join(', '),
+    });
+    results.push({ step: 'screenshot', result: screenshotPath });
+
+    return results;
+  },
+});

package/clis/geogebra/utils.js

@@ -0,0 +1,271 @@
+import { ArgumentError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+/**
+ * Shared utilities for GeoGebra adapters.
+ *
+ * GeoGebra Geometry exposes a `ggbApplet` JavaScript API on the page after
+ * the GWT-compiled app initializes. All adapters share the same pattern:
+ * navigate → wait for applet → call API via page.evaluate().
+ */
+
+const GEOGEBRA_URL = 'https://www.geogebra.org/geometry';
+const APPLET_WAIT_MS = 15_000;
+
+export function unwrapBridgeEnvelope(value) {
+  if (value && typeof value === 'object' && 'data' in value && 'session' in value) {
+    return value.data;
+  }
+  return value;
+}
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function normalizeLabel(value, label = 'label') {
+  const normalized = String(value ?? '').trim();
+  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(normalized)) {
+    throw new ArgumentError(`${label} must be an ASCII GeoGebra label like A, B1, or poly_1`);
+  }
+  return normalized;
+}
+
+export function normalizeLabelList(value, label, min, max = Infinity) {
+  const parts = String(value ?? '').split(',').map(s => s.trim()).filter(Boolean);
+  if (parts.length < min || parts.length > max) {
+    throw new ArgumentError(`${label} must contain ${min === max ? min : `${min}-${max}`} comma-separated labels`);
+  }
+  return parts.map((part, idx) => normalizeLabel(part, `${label}[${idx + 1}]`));
+}
+
+export function normalizeNumber(value, label, { defaultValue, positive = false } = {}) {
+  const raw = value == null || value === '' ? defaultValue : value;
+  const number = Number(raw);
+  if (!Number.isFinite(number) || (positive && number <= 0)) {
+    throw new ArgumentError(`${label} must be a ${positive ? 'positive ' : ''}finite number`);
+  }
+  return number;
+}
+
+export function normalizeCoords(value) {
+  const parts = String(value ?? '').split(',').map(s => s.trim());
+  if (parts.length !== 2) {
+    throw new ArgumentError('coords must be in "x,y" format (e.g. "1,2")');
+  }
+  return parts.map((part, idx) => normalizeNumber(part, idx === 0 ? 'x' : 'y'));
+}
+
+export function requireGgbSuccess(result, message) {
+  if (!isPlainObject(result)) {
+    throw new CommandExecutionError(`${message}: malformed GeoGebra result`);
+  }
+  if (!result.ok) {
+    throw new CommandExecutionError(result.error || message);
+  }
+  return result;
+}
+
+/**
+ * Navigate to GeoGebra Geometry (if not already there) and wait for
+ * the ggbApplet API to become available.
+ */
+export async function ensureApplet(page) {
+  let currentUrl = '';
+  try {
+    currentUrl = await page.getCurrentUrl();
+  } catch {
+    currentUrl = '';
+  }
+  // If already on the geometry page, check if applet is ready without re-navigating
+  if (currentUrl?.includes('geogebra.org/geometry')) {
+    try {
+      const ready = unwrapBridgeEnvelope(await page.evaluate(`typeof ggbApplet !== 'undefined' && typeof ggbApplet.evalCommand === 'function'`));
+      if (ready) return;
+    } catch (err) {
+      throw new CommandExecutionError(`Failed to detect GeoGebra applet: ${err?.message || err}`);
+    }
+  }
+  // Navigate to GeoGebra Geometry
+  try {
+    await page.goto(GEOGEBRA_URL);
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to load GeoGebra Geometry: ${err?.message || err}`);
+  }
+
+  let ready;
+  try {
+    ready = unwrapBridgeEnvelope(await page.evaluate(`
+      (async () => {
+        const deadline = Date.now() + ${APPLET_WAIT_MS};
+        while (Date.now() < deadline) {
+          if (typeof ggbApplet !== 'undefined' && typeof ggbApplet.evalCommand === 'function') {
+            return true;
+          }
+          await new Promise(r => setTimeout(r, 500));
+        }
+        return false;
+      })()
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to detect GeoGebra applet: ${err?.message || err}`);
+  }
+  if (ready !== true) {
+    throw new CommandExecutionError('ggbApplet not available after waiting. Make sure the GeoGebra Geometry page is fully loaded.');
+  }
+}
+
+/**
+ * Execute a GeoGebra command string via ggbApplet.evalCommandGetLabels.
+ * evalCommandGetLabels both executes the command and returns the created
+ * object label(s). We use it instead of evalCommand to avoid double-execution.
+ * Returns { ok, label } where label is the resulting object label(s).
+ */
+export async function ggbEval(page, cmd) {
+  let result;
+  try {
+    result = unwrapBridgeEnvelope(await page.evaluate(`
+      (cmd => {
+        if (typeof ggbApplet === 'undefined' || typeof ggbApplet.evalCommandGetLabels !== 'function') {
+          return { ok: false, label: '', beforeCount: 0, afterCount: 0, error: 'ggbApplet is not ready' };
+        }
+        const collectNames = () => {
+          let names = ggbApplet.getAllObjectNames();
+          if (typeof names === 'string') {
+            names = names.split(',').map(s => s.trim()).filter(Boolean);
+          }
+          return Array.isArray(names) ? names : [];
+        };
+        const beforeCount = collectNames().length;
+        const label = ggbApplet.evalCommandGetLabels(cmd);
+        const afterCount = collectNames().length;
+        const dialogText = [...document.querySelectorAll('[role="dialog"], .gwt-DialogBox')]
+          .map(node => node.textContent?.trim() || '')
+          .find(text => /error|unknown command|错误|未知的指令/i.test(text)) || '';
+        return {
+          ok: label !== '' || afterCount > beforeCount,
+          label,
+          beforeCount,
+          afterCount,
+          error: dialogText || null,
+        };
+      })(${JSON.stringify(cmd)})
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to execute GeoGebra command: ${err?.message || err}`);
+  }
+  if (!isPlainObject(result) || typeof result.ok !== 'boolean') {
+    throw new CommandExecutionError('GeoGebra command returned malformed result');
+  }
+  return result;
+}
+
+/**
+ * List all currently known GeoGebra objects, optionally filtered by type.
+ */
+export async function ggbListObjects(page, filterType) {
+  const normalizedFilter = filterType ? String(filterType).toLowerCase() : '';
+  let objects;
+  try {
+    objects = unwrapBridgeEnvelope(await page.evaluate(`
+      (filterType => {
+        const api = ggbApplet;
+        let names = api.getAllObjectNames();
+        if (typeof names === 'string') {
+          names = names.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        if (!Array.isArray(names)) return { error: 'Object names are not an array' };
+        const result = [];
+        for (const name of names) {
+          try {
+            const type = api.getObjectType(name);
+            if (!type) return { error: 'Object has no type', name };
+            if (filterType && type.toLowerCase() !== filterType) continue;
+            result.push({
+              name,
+              type,
+              value: api.getValueString(name) || '',
+              visible: api.getVisible(name),
+            });
+          } catch (err) {
+            return { error: err?.message || String(err), name };
+          }
+        }
+        return result;
+      })(${JSON.stringify(normalizedFilter)})
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to list GeoGebra objects: ${err?.message || err}`);
+  }
+  if (objects && typeof objects === 'object' && !Array.isArray(objects) && objects.error) {
+    const nameSuffix = objects.name ? ` for ${objects.name}` : '';
+    throw new CommandExecutionError(`Failed to list GeoGebra objects${nameSuffix}: ${objects.error}`);
+  }
+  if (!Array.isArray(objects)) {
+    throw new CommandExecutionError('GeoGebra object list returned malformed result');
+  }
+  return objects;
+}
+
+/**
+ * Poll until the object count reaches the requested minimum.
+ */
+export async function ggbWaitForObjectCount(page, minCount, timeoutMs = 4_000) {
+  const normalizedMinCount = normalizeNumber(minCount, 'minCount', { positive: true });
+  const normalizedTimeoutMs = normalizeNumber(timeoutMs, 'timeoutMs', { positive: true });
+  let count;
+  try {
+    count = unwrapBridgeEnvelope(await page.evaluate(`
+      (async () => {
+        const deadline = Date.now() + ${normalizedTimeoutMs};
+        while (Date.now() < deadline) {
+          let names = ggbApplet.getAllObjectNames();
+          if (typeof names === 'string') {
+            names = names.split(',').map(s => s.trim()).filter(Boolean);
+          }
+          if (Array.isArray(names) && names.length >= ${normalizedMinCount}) {
+            return names.length;
+          }
+          await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        let names = ggbApplet.getAllObjectNames();
+        if (typeof names === 'string') {
+          names = names.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        return Array.isArray(names) ? names.length : 0;
+      })()
+    `));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed waiting for GeoGebra object count: ${err?.message || err}`);
+  }
+  if (!Number.isFinite(Number(count))) {
+    throw new CommandExecutionError('GeoGebra object count returned malformed result');
+  }
+  return Number(count);
+}
+
+/**
+ * Read a property from a GeoGebra object.
+ */
+export async function ggbGetProperty(page, objName, property) {
+  try {
+    return unwrapBridgeEnvelope(await page.evaluate(`
+      (objName, property) => {
+        const api = ggbApplet;
+        switch (property) {
+          case 'type': return api.getObjectType(objName);
+          case 'value': return api.getValueString(objName);
+          case 'color': return api.getColor(objName);
+          case 'visible': return api.getVisible(objName);
+          case 'caption': return api.getCaption(objName) || '';
+          case 'xcoord': return api.getXcoord(objName);
+          case 'ycoord': return api.getYcoord(objName);
+          case 'definition': return api.getDefinitionString(objName);
+          case 'command': return api.getCommandString(objName);
+          default: return null;
+        }
+      }
+    `, objName, property));
+  } catch (err) {
+    throw new CommandExecutionError(`Failed to read GeoGebra object property: ${err?.message || err}`);
+  }
+}