de-shell 0.2.0__py3-none-any.whl

de_shell/js/renderer/shellState.ts

@@ -0,0 +1,310 @@
+/**
+ * shellState.ts — the app-chrome state every shell app keeps.
+ *
+ * Status line, busy indicator, the log ring, first-run environment setup, the
+ * "backend died" latch, per-window computing overlays, and toolbar action
+ * state. None of it knows what the data is; all of it was written twice (SpyDE
+ * in a reducer, Ground Crew in ad-hoc `useState`) before landing here.
+ *
+ * **The window/figure registry is deliberately NOT here.** SpyDE's is entangled
+ * with its named-view/chip system (`view`, `view_label`, strain components) and
+ * Ground Crew has no window registry at all — one fixed pane. Extracting it now
+ * would be generalising from a single consumer, so it stays in SpyDE until a
+ * second app actually needs it.
+ *
+ * ## Composing
+ *
+ * An app's state EXTENDS `ShellState` and its reducer delegates:
+ *
+ *     function appReducer(state: AppState, action: AppAction): AppState {
+ *       switch (action.type) {
+ *         case 'MY_THING': return …
+ *         default: return shellReducer(state, action as ShellAction)
+ *       }
+ *     }
+ *
+ * `shellReducer` is generic over the state type and returns it unchanged for an
+ * action it does not own, so the delegation is safe in either order.
+ */
+
+/**
+ * One application-log record streamed from the backend.
+ *
+ * `seq` is a renderer-assigned monotonic id, stamped once as the record enters
+ * the buffer. It is the STABLE React key + height-cache key for a virtualised
+ * log list: the buffer is a ring (old records drop off the front), so an array
+ * INDEX identifies a different record after every shift, which would defeat
+ * both row memoisation and a measured-height cache.
+ *
+ * `area` is the subsystem tag the app registered (see de_shell.log_stream), and
+ * is optional because a record can predate registration.
+ */
+export interface LogEntry {
+  level: string
+  name: string
+  area?: string
+  msg: string
+  time: number
+  seq?: number
+}
+
+export interface SubItem {
+  name: string
+  color: string
+  vtype?: string
+  calculation?: string
+}
+
+export type EnvPhase =
+  | 'resolving' | 'downloading' | 'installing' | 'building' | 'torch' | 'working'
+
+export interface EnvSetupState {
+  phase: EnvPhase
+  /** Friendly current-step headline. */
+  step: string
+  /** 0–100 for a download we can measure, else null. */
+  percent: number | null
+  /** Rolling raw output tail (bounded). */
+  lines: string[]
+}
+
+export interface ShellState {
+  status: string
+  ready: boolean
+  /** Long file-read / open busy indicator. */
+  loading: { busy: boolean; text: string }
+  /** Raw stdout/stderr from the backend (bounded). */
+  streamLines: Array<{ text: string; kind: 'stdout' | 'stderr' }>
+  /** Application-log records (the log panel). */
+  logEntries: LogEntry[]
+  /** Current backend verbosity (DEBUG…CRITICAL). */
+  logLevel: string
+  /** Set when the Python sidecar dies; surfaces a blocking banner. */
+  backendExited: { code: number | null; reason?: string } | null
+  /** First-run `uv sync` progress; drives the floating setup overlay. */
+  envSetup: EnvSetupState | null
+  /** windowIds with a long compute in flight (→ floating overlay). */
+  computingWindows: Set<number>
+  /** windowId → action names with live output. */
+  activeActions: Map<number, Set<string>>
+  /** windowId → action → dynamic chips. */
+  subItems: Map<number, Map<string, SubItem[]>>
+}
+
+/** Max buffered log records (the renderer-side ring buffer). */
+export const LOG_MAX = 1000
+
+/** Matching bound for raw stdout/stderr, which is noisier and less useful. */
+export const STREAM_MAX = 500
+
+export const shellInitialState: ShellState = {
+  status: 'Starting…',
+  ready: false,
+  loading: { busy: false, text: '' },
+  streamLines: [],
+  logEntries: [],
+  logLevel: 'INFO',
+  backendExited: null,
+  envSetup: null,
+  computingWindows: new Set(),
+  activeActions: new Map(),
+  subItems: new Map(),
+}
+
+export type ShellAction =
+  | { type: 'STATUS'; text: string }
+  | { type: 'LOADING'; busy: boolean; text: string }
+  | { type: 'STREAM'; text: string; kind: 'stdout' | 'stderr' }
+  | { type: 'LOG'; entries: LogEntry[] }
+  | { type: 'LOG_BACKFILL'; entries: LogEntry[] }
+  | { type: 'LOG_CLEAR' }
+  | { type: 'LOG_LEVEL'; level: string }
+  | { type: 'BACKEND_EXITED'; code: number | null; reason?: string }
+  | { type: 'ENV_SETUP_START' }
+  | { type: 'ENV_SETUP_PROGRESS'; phase?: EnvPhase; step?: string; percent: number | null; raw: string }
+  | { type: 'ENV_SETUP_DONE' }
+  | { type: 'WINDOW_COMPUTING'; windowId: number; computing: boolean }
+  | { type: 'ACTION_ACTIVE'; windowId: number; name: string; active: boolean }
+  | { type: 'SUB_ITEM'; windowId: number; action: string; name: string; color: string; vtype?: string; calculation?: string; active: boolean }
+
+/**
+ * Reduce the shell's slice. Generic over the app's state so it composes as a
+ * `default:` branch; returns *state* untouched for anything it does not own.
+ */
+export function shellReducer<S extends ShellState>(state: S, action: ShellAction): S {
+  switch (action.type) {
+    case 'STATUS':
+      return { ...state, status: action.text }
+
+    case 'LOADING':
+      return { ...state, loading: { busy: action.busy, text: action.text } }
+
+    case 'STREAM':
+      return {
+        ...state,
+        streamLines: [...state.streamLines.slice(-STREAM_MAX),
+          { text: action.text, kind: action.kind }],
+      }
+
+    // A BATCH of records (hosts coalesce per animation frame) — one array copy
+    // and one render for a whole burst, instead of one per line.
+    case 'LOG': {
+      if (action.entries.length === 0) return state
+      const merged = state.logEntries.concat(action.entries)
+      return {
+        ...state,
+        logEntries: merged.length > LOG_MAX ? merged.slice(-LOG_MAX) : merged,
+      }
+    }
+
+    case 'LOG_BACKFILL':
+      return { ...state, logEntries: action.entries.slice(-LOG_MAX) }
+
+    // Empty the panel. A renderer-side clear ONLY — the backend's own buffer is
+    // untouched, so a later `log_backfill` legitimately brings the history
+    // back. Belongs here rather than in an app: the buffer it empties is this
+    // reducer's, and an app-level high-water mark cannot survive the ring
+    // dropping records off the front (the records carry no id of their own
+    // until a host stamps `seq`).
+    case 'LOG_CLEAR':
+      return state.logEntries.length === 0 ? state : { ...state, logEntries: [] }
+
+    case 'LOG_LEVEL':
+      return { ...state, logLevel: action.level }
+
+    case 'BACKEND_EXITED':
+      return {
+        ...state,
+        backendExited: { code: action.code, reason: action.reason },
+        // A setup failure surfaces via BACKEND_EXITED — drop the setup overlay
+        // so the two don't stack.
+        envSetup: null,
+        ready: false,
+        status: 'Backend stopped',
+      }
+
+    case 'ENV_SETUP_START':
+      return {
+        ...state,
+        envSetup: {
+          phase: 'resolving',
+          step: 'Preparing the analysis environment',
+          percent: null,
+          lines: [],
+        },
+        status: 'Setting up the analysis environment…',
+      }
+
+    case 'ENV_SETUP_PROGRESS': {
+      const prev = state.envSetup ?? {
+        phase: 'resolving' as EnvPhase,
+        step: 'Preparing the analysis environment',
+        percent: null,
+        lines: [],
+      }
+      // Keep the last meaningful step/phase when a noisy line parses to nothing;
+      // always append the raw line to the bounded tail so it visibly moves.
+      const lines = [...prev.lines, action.raw].slice(-200)
+      return {
+        ...state,
+        envSetup: {
+          phase: action.phase ?? prev.phase,
+          step: action.step ?? prev.step,
+          percent: action.percent,
+          lines,
+        },
+      }
+    }
+
+    case 'ENV_SETUP_DONE':
+      return { ...state, envSetup: null }
+
+    case 'WINDOW_COMPUTING': {
+      const has = state.computingWindows.has(action.windowId)
+      if (action.computing === has) return state   // no-op re-emit
+      const computingWindows = new Set(state.computingWindows)
+      if (action.computing) computingWindows.add(action.windowId)
+      else computingWindows.delete(action.windowId)
+      return { ...state, computingWindows }
+    }
+
+    case 'ACTION_ACTIVE': {
+      const activeActions = new Map(state.activeActions)
+      const set = new Set(activeActions.get(action.windowId) ?? [])
+      if (action.active) set.add(action.name)
+      else set.delete(action.name)
+      activeActions.set(action.windowId, set)
+      return { ...state, activeActions }
+    }
+
+    case 'SUB_ITEM': {
+      const subItems = new Map(state.subItems)
+      const byAction = new Map(subItems.get(action.windowId) ?? new Map<string, SubItem[]>())
+      const list = (byAction.get(action.action) ?? []).filter(i => i.name !== action.name)
+      if (action.active) list.push({
+        name: action.name, color: action.color,
+        vtype: action.vtype, calculation: action.calculation,
+      })
+      byAction.set(action.action, list)
+      subItems.set(action.windowId, byAction)
+      return { ...state, subItems }
+    }
+
+    default:
+      return state
+  }
+}
+
+/**
+ * Map a backend message to a shell action, or null if the shell does not own it.
+ *
+ * Lets an app route the chrome messages without restating them:
+ *
+ *     const shellAction = toShellAction(msg)
+ *     if (shellAction) { dispatch(shellAction); return }
+ *
+ * `log` is deliberately NOT handled here. Hosts coalesce log records per frame
+ * before dispatching a batched `LOG` — mapping one message to one action would
+ * undo that and re-render per line.
+ */
+export function toShellAction(msg: Record<string, unknown>): ShellAction | null {
+  switch (msg.type) {
+    case 'status':
+      return { type: 'STATUS', text: String(msg.text ?? '') }
+    case 'loading':
+      return { type: 'LOADING', busy: Boolean(msg.busy), text: String(msg.text ?? '') }
+    case 'stream':
+      return {
+        type: 'STREAM', text: String(msg.text ?? ''),
+        kind: msg.kind === 'stderr' ? 'stderr' : 'stdout',
+      }
+    case 'log_backfill':
+      return { type: 'LOG_BACKFILL', entries: (msg.entries ?? []) as LogEntry[] }
+    case 'log_level':
+      return { type: 'LOG_LEVEL', level: String(msg.level ?? 'INFO') }
+    case 'backend_exited':
+      return {
+        type: 'BACKEND_EXITED',
+        code: (msg.code ?? null) as number | null,
+        reason: msg.reason as string | undefined,
+      }
+    case 'window_computing':
+      return {
+        type: 'WINDOW_COMPUTING',
+        windowId: Number(msg.window_id),
+        computing: Boolean(msg.computing),
+      }
+    case 'env_setup':
+      if (msg.event === 'start') return { type: 'ENV_SETUP_START' }
+      if (msg.event === 'done') return { type: 'ENV_SETUP_DONE' }
+      return {
+        type: 'ENV_SETUP_PROGRESS',
+        phase: msg.phase as EnvPhase | undefined,
+        step: msg.step as string | undefined,
+        percent: (msg.percent ?? null) as number | null,
+        raw: String(msg.raw ?? ''),
+      }
+    default:
+      return null
+  }
+}

de_shell/js/testing/harness.cjs

@@ -0,0 +1,244 @@
+/**
+ * harness.cjs — launching a shell app under Playwright, for any of the three.
+ *
+ * Generalised from SpyDE's electron/tests/_harness.cjs. Everything here is
+ * app-agnostic; domain helpers (SpyDE's loadTestVectors, navWindow,
+ * dragCrosshair) stay in the app's own test directory.
+ *
+ * The two things this exists to get right, both learned the hard way in SpyDE:
+ *
+ *   1. **Profile isolation.** Electron defaults to a per-app profile directory
+ *      that a developer's `npm run dev` instance may already hold a Chromium
+ *      singleton lock on. A test launched against it does not fail with a clear
+ *      error — it HANGS, and Playwright reports a bare launch timeout with no
+ *      hint that another process owns the directory. Every launch gets a fresh
+ *      temp profile.
+ *
+ *   2. **Backend errors are invisible by default.** The Python side talks over
+ *      the PLOTAPP stdout protocol, which the Electron main process consumes —
+ *      so a backend that dies mid-test dies SILENTLY. The app's log-level env
+ *      var makes it tee logging to stderr, which this captures into `logBuffer`.
+ */
+// The APP's Playwright, never one found beside this file. This package reaches
+// an app through a symlink into a checkout that may carry its own node_modules
+// (for the shell's typecheck), and Playwright refuses to be loaded twice
+// ("Requiring @playwright/test second time"). Resolving from the working
+// directory — the app's, when its `playwright test` runs — picks the copy the
+// runner already loaded; the fallback is for a bare `node --test` here.
+function appRequire(name) {
+  try { return require(require.resolve(name, { paths: [process.cwd()] })) } catch { return require(name) }
+}
+const { _electron: electron } = appRequire('@playwright/test')
+const { spawnSync } = require('child_process')
+const { mkdtempSync } = require('fs')
+const { join } = require('path')
+const { tmpdir } = require('os')
+
+/**
+ * Launch a shell app.
+ *
+ * @param {object} opts
+ * @param {string} opts.appDir      App root (the directory holding out/main/index.js).
+ * @param {string} opts.appId       Shell appId — namespaces the temp profile dir.
+ * @param {string} [opts.readyLog]  Stderr/stdout substring meaning "backend up".
+ * @param {string[]} [opts.readyMessages] PLOTAPP message types to wait for.
+ * @param {object} [opts.env]       Extra environment for the app process.
+ * @param {number} [opts.timeout]   Milliseconds to wait for the ready signals.
+ */
+async function launchApp(opts) {
+  const {
+    appDir, appId, readyLog = null, readyMessages = ['ready'],
+    env = {}, timeout = 60_000,
+  } = opts
+  if (!appDir || !appId) throw new Error('launchApp needs { appDir, appId }')
+
+  const app = await electron.launch({
+    // Resolve Electron from the APP's tree, not Playwright's. Without an
+    // explicit path, playwright-core does a bare require('electron/index.js')
+    // from its own (usually root-hoisted) location — in a workspace layout
+    // that can find a DIFFERENT Electron than the one the app declares (an
+    // auto-installed peer once put 43 at the root while the app shipped 34,
+    // and every e2e silently tested the wrong Chromium). appDir is the
+    // directory holding the app's package.json, so its node_modules wins.
+    executablePath: require(require.resolve('electron/index.js', { paths: [appDir] })),
+    args: [
+      join(appDir, 'out', 'main', 'index.js'),
+      `--user-data-dir=${mkdtempSync(join(tmpdir(), `${appId}-e2e-profile-`))}`,
+    ],
+    env: { ...process.env, ...env },
+  })
+
+  const backend = createBackend(app)
+  const page = await firstWindowWithLog(app, backend.logBuffer, timeout)
+
+  // Surface renderer exceptions rather than letting a blank page look like a
+  // slow one. Collected, not thrown, so a spec decides what is fatal.
+  const jsErrors = []
+  page.on('pageerror', (e) => jsErrors.push(String(e)))
+
+  if (readyLog) await backend.waitForLog(readyLog, timeout)
+  for (const type of readyMessages) await backend.waitForMessage(type, timeout)
+
+  return {
+    app, page, backend, jsErrors,
+    assertNoJsErrors: () => assertNoJsErrors(jsErrors),
+    close: (opts) => closeApp(app, opts),
+  }
+}
+
+/**
+ * `app.firstWindow()` with an EXPLICIT timeout and the backend log attached to
+ * the failure. Playwright's bare "firstWindow timeout" hides the actual cause,
+ * which is almost always in the app's stderr (uv missing, env sync failed,
+ * Python died on import) — the harness buffered it; say it.
+ */
+async function firstWindowWithLog(app, logBuffer, timeout = 60_000) {
+  try {
+    return await app.firstWindow({ timeout })
+  } catch (e) {
+    throw new Error(
+      `no app window appeared within ${timeout}ms (${e.message}) — ` +
+      'the main process likely failed before creating it.\n' +
+      `last 40 log lines:\n${logBuffer.slice(-40).join('\n')}`)
+  }
+}
+
+/**
+ * Close the app with a DEADLINE, then hard-kill the whole process tree if the
+ * close wedged. A backend stuck mid-compute can hold `app.close()` up past the
+ * runner's timeout, leaving an Electron tree alive that (for a DE app) still
+ * owns the server's single connection — every later launch then hangs on a
+ * connection that cannot be made. Returns 'closed' | 'killed' | 'noop' so a
+ * caller can log what teardown actually did.
+ */
+async function closeApp(app, opts = {}) {
+  const { timeout = 15_000, killTree = hardKillTree } = opts
+  if (!app) return 'noop'
+  const pid = app.process()?.pid
+  const closed = await new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), timeout)
+    timer.unref?.()
+    Promise.resolve()
+      .then(() => app.close())
+      .then(() => { clearTimeout(timer); resolve(true) },
+            () => { clearTimeout(timer); resolve(false) })
+  })
+  if (closed) return 'closed'
+  if (pid) killTree(pid)
+  return pid ? 'killed' : 'noop'
+}
+
+/** Force-kill `pid` AND everything under it (the Python sidecar and its
+ *  workers ride below the Electron root). */
+function hardKillTree(pid) {
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' })
+    } else {
+      process.kill(pid, 'SIGKILL')
+    }
+  } catch { /* already gone */ }
+}
+
+/** Buffer the app process's stdio and expose waiters over it. */
+function createBackend(app) {
+  const logBuffer = []
+  const waiters = []
+
+  const push = (text) => {
+    for (const line of String(text).split('\n')) {
+      if (!line.trim()) continue
+      logBuffer.push(line)
+      for (const w of waiters.slice()) {
+        if (w.test(line)) {
+          waiters.splice(waiters.indexOf(w), 1)
+          w.resolve(line)
+        }
+      }
+    }
+  }
+
+  app.process().stdout?.on('data', (d) => push(d.toString()))
+  app.process().stderr?.on('data', (d) => push(d.toString()))
+
+  /** Resolve when a line contains `substr` — including lines already buffered,
+   *  so a caller that starts waiting late does not miss it. */
+  function waitForLog(substr, timeout = 60_000) {
+    const hit = logBuffer.find((l) => l.includes(substr))
+    if (hit) return Promise.resolve(hit)
+    return new Promise((resolve, reject) => {
+      const w = { test: (l) => l.includes(substr), resolve }
+      waiters.push(w)
+      setTimeout(() => {
+        const i = waiters.indexOf(w)
+        if (i >= 0) {
+          waiters.splice(i, 1)
+          reject(new Error(
+            `timed out waiting for log ${JSON.stringify(substr)}\n` +
+            `last 40 lines:\n${logBuffer.slice(-40).join('\n')}`))
+        }
+      }, timeout)
+    })
+  }
+
+  /** Resolve when a PLOTAPP message of `type` is emitted. */
+  function waitForMessage(type, timeout = 60_000) {
+    return waitForLog(`"type": "${type}"`, timeout).catch(() =>
+      waitForLog(`"type":"${type}"`, timeout))
+  }
+
+  return { logBuffer, waitForLog, waitForMessage, errorLines: () => errorLines(logBuffer) }
+}
+
+/** Lines that look like a Python failure. Used to fail a spec loudly rather than
+ *  letting a broken backend read as a slow one. */
+function errorLines(logBuffer) {
+  return logBuffer.filter((l) =>
+    /Traceback|ModuleNotFoundError|ImportError|Fatal Python error|ERROR/.test(l))
+}
+
+function assertNoJsErrors(jsErrors) {
+  if (jsErrors.length) {
+    throw new Error('renderer JS errors:\n' + jsErrors.join('\n'))
+  }
+}
+
+/**
+ * Count pixels in every <canvas> on the page (figures live in iframes, so this
+ * walks all frames).
+ *
+ * `kind` is 'bright' | 'red' | 'green'. Anything else counts NOTHING and would
+ * make an assertion pass vacuously — so unknown kinds throw instead.
+ */
+async function countColorPixels(page, kind) {
+  const KINDS = ['bright', 'red', 'green']
+  if (!KINDS.includes(kind)) {
+    throw new Error(`countColorPixels: unknown kind ${JSON.stringify(kind)} (use ${KINDS.join('|')})`)
+  }
+  let total = 0
+  for (const frame of page.frames()) {
+    try {
+      total += await frame.evaluate((k) => {
+        let n = 0
+        for (const c of Array.from(document.querySelectorAll('canvas'))) {
+          const ctx = c.getContext('2d')
+          if (!ctx || !c.width || !c.height) continue
+          const d = ctx.getImageData(0, 0, c.width, c.height).data
+          for (let p = 0; p < d.length; p += 4) {
+            const r = d[p], g = d[p + 1], b = d[p + 2]
+            if (k === 'bright' && (r > 30 || g > 30 || b > 30)) n++
+            if (k === 'red' && r > 120 && g < 90 && b < 90) n++
+            if (k === 'green' && g > 150 && r < 130 && b > 50 && b < 170) n++
+          }
+        }
+        return n
+      }, kind)
+    } catch { /* frame detached mid-evaluate */ }
+  }
+  return total
+}
+
+module.exports = {
+  launchApp, createBackend, countColorPixels, assertNoJsErrors, errorLines,
+  firstWindowWithLog, closeApp, hardKillTree,
+}

de_shell/js/testing/harness.test.cjs

@@ -0,0 +1,73 @@
+/**
+ * harness.test.cjs — node:test unit tests for the harness's failure paths.
+ *
+ * Two teardown/startup behaviours learned the hard way:
+ *
+ *   1. A window that never appears must fail with the BACKEND LOG attached —
+ *      Playwright's bare "firstWindow timeout" hides the uv/env error that
+ *      caused it.
+ *   2. `app.close()` can wedge (a backend stuck mid-compute holds quit up), and
+ *      a wedged close leaves the Electron tree alive holding the DE Server's
+ *      single connection — so teardown needs a deadline and a hard tree-kill.
+ *
+ * Run: `node --test src/harness.test.cjs` (from packages/shell-testing/), or
+ * via the `test:unit` npm script.
+ */
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+const { firstWindowWithLog, closeApp } = require('./harness.cjs')
+
+test('a missing first window reports the backend log, not a bare timeout', async () => {
+  const app = {
+    firstWindow: async () => { throw new Error('Timeout 60000ms exceeded.') },
+  }
+  const logBuffer = ['[env-setup] running full locked uv sync',
+                     'error: uv exploded for reasons']
+  await assert.rejects(
+    () => firstWindowWithLog(app, logBuffer, 60_000),
+    (err) => {
+      assert.match(err.message, /window/i)
+      assert.match(err.message, /uv exploded for reasons/,
+        'the backend log tail is missing from the failure')
+      return true
+    },
+  )
+})
+
+test('a clean close does not kill anything', async () => {
+  const killed = []
+  const app = {
+    process: () => ({ pid: 4242 }),
+    close: async () => {},
+  }
+  const outcome = await closeApp(app, { timeout: 1000, killTree: (pid) => killed.push(pid) })
+  assert.equal(outcome, 'closed')
+  assert.deepEqual(killed, [])
+})
+
+test('a wedged close is hard-killed at the deadline', async () => {
+  const killed = []
+  const app = {
+    process: () => ({ pid: 4242 }),
+    close: () => new Promise(() => {}),   // never resolves — the wedge
+  }
+  const outcome = await closeApp(app, { timeout: 100, killTree: (pid) => killed.push(pid) })
+  assert.equal(outcome, 'killed')
+  assert.deepEqual(killed, [4242])
+})
+
+test('a close that rejects still hard-kills the tree', async () => {
+  const killed = []
+  const app = {
+    process: () => ({ pid: 4242 }),
+    close: async () => { throw new Error('target closed') },
+  }
+  const outcome = await closeApp(app, { timeout: 1000, killTree: (pid) => killed.push(pid) })
+  assert.equal(outcome, 'killed')
+  assert.deepEqual(killed, [4242])
+})
+
+test('closeApp tolerates a missing app', async () => {
+  assert.equal(await closeApp(null), 'noop')
+  assert.equal(await closeApp(undefined), 'noop')
+})