de-shell 0.2.0__py3-none-any.whl

de_shell/js/renderer/figureBridge.ts

@@ -0,0 +1,169 @@
+/**
+ * figureBridge.ts — routing backend state into figure iframes.
+ *
+ * An anyplotlib figure lives in an iframe and is fed by `postMessage`. The
+ * backend sends only CHANGES, so a message that arrives before its iframe has
+ * mounted a listener is gone for good — silently, because posting into an
+ * unmounted frame is a no-op, not an error. That single fact is why this is a
+ * stateful bridge rather than a forwarding function: every state is RETAINED so
+ * a frame can be replayed when it loads.
+ *
+ * Lifted from SpyDE's implementation, which had already paid for the three
+ * non-obvious parts:
+ *
+ * 1. **Replay takes an explicit target.** A figure can be mounted more than
+ *    once under the same figId (SpyDE's report cell and its presented slide),
+ *    and the registry holds ONE element per id. Resolving the target from the
+ *    map means whichever mounted last wins, so a freshly-loaded frame would
+ *    push its state into its SIBLING and receive nothing. Which mount won was a
+ *    race, so a presented deck came up blank on some machines and not others.
+ *    A frame that has just loaded passes ITSELF.
+ *
+ * 2. **Binary frames stash per PANEL, not per pixel field.** `key` is the pixel
+ *    field ("image_b64" / "detail_b64" / …) and is identical across panels; the
+ *    panel is identified by `header.geom`. Keying by `key` alone let each panel
+ *    overwrite the previous one, so a multi-panel figure retained exactly one
+ *    frame however many panels it had — and replayed as one drawn panel and the
+ *    rest blank-but-for-their-scale-bars.
+ *
+ * 3. **Transfer the buffer, but replay a COPY.** Transferring detaches the
+ *    original, which would empty the stash the first time it was replayed.
+ */
+
+export interface BinaryFrame {
+  key: string
+  header: unknown
+  buffer: Uint8Array
+}
+
+/** A `{current}` box, so these drop straight into a React ref position. */
+export interface RefLike<T> {
+  current: T
+}
+
+export interface FigureBridge {
+  /** figId → the iframe currently registered for it. */
+  iframes: RefLike<Map<string, HTMLIFrameElement>>
+  /** figId → (state key → latest value). */
+  states: RefLike<Map<string, Map<string, unknown>>>
+  /** figId → (`geom::pixelField` → latest binary frame). */
+  binaryStates: RefLike<Map<string, Map<string, BinaryFrame>>>
+
+  registerIframe(figId: string, el: HTMLIFrameElement | null): void
+  applyState(figId: string, key: string, value: unknown): void
+  applyBinary(figId: string, key: string, header: unknown, bytes: Uint8Array): void
+  replay(figId: string, target?: HTMLIFrameElement): void
+  evict(figId: string): void
+  post(figId: string, message: Record<string, unknown>, target?: HTMLIFrameElement): boolean
+  dump(classify?: (el: HTMLIFrameElement | undefined) => string): Record<string, unknown>[]
+}
+
+export function createFigureBridge(
+  log: (label: string, detail: Record<string, unknown>) => void = () => {},
+): FigureBridge {
+  const iframes: RefLike<Map<string, HTMLIFrameElement>> = { current: new Map() }
+  const states: RefLike<Map<string, Map<string, unknown>>> = { current: new Map() }
+  const binaryStates: RefLike<Map<string, Map<string, BinaryFrame>>> = { current: new Map() }
+
+  function post(figId: string, message: Record<string, unknown>,
+                target?: HTMLIFrameElement): boolean {
+    const iframe = target ?? iframes.current.get(figId)
+    if (!iframe?.contentWindow) return false
+    iframe.contentWindow.postMessage(message, '*')
+    return true
+  }
+
+  function registerIframe(figId: string, el: HTMLIFrameElement | null): void {
+    if (el) iframes.current.set(figId, el)
+    else iframes.current.delete(figId)
+  }
+
+  function applyState(figId: string, key: string, value: unknown): void {
+    let slot = states.current.get(figId)
+    if (!slot) { slot = new Map(); states.current.set(figId, slot) }
+    slot.set(key, value)
+    post(figId, { type: 'awi_state', key, value })
+  }
+
+  function applyBinary(figId: string, key: string, header: unknown,
+                       bytes: Uint8Array): void {
+    if (bytes) {
+      let slot = binaryStates.current.get(figId)
+      if (!slot) { slot = new Map(); binaryStates.current.set(figId, slot) }
+      const geom = (header as { geom?: string } | undefined)?.geom
+      // Mirrors the figure ESM's own slot convention, `geom::pixelKey`.
+      const stashKey = geom ? `${geom}::${key}` : key
+      // slice() because the postMessage below TRANSFERS the buffer and detaches
+      // the original — the stash has to own its own copy.
+      slot.set(stashKey, { key, header, buffer: bytes.slice() })
+    }
+    const iframe = iframes.current.get(figId)
+    iframe?.contentWindow?.postMessage(
+      { type: 'awi_state_binary', key, header, buffer: bytes },
+      '*',
+      bytes?.buffer ? [bytes.buffer] : [],
+    )
+  }
+
+  function replay(figId: string, target?: HTMLIFrameElement): void {
+    const iframe = target ?? iframes.current.get(figId)
+    if (!iframe?.contentWindow) return
+    const slot = states.current.get(figId)
+    if (slot) {
+      for (const [key, value] of slot) {
+        iframe.contentWindow.postMessage({ type: 'awi_state', key, value }, '*')
+      }
+    }
+    const binSlot = binaryStates.current.get(figId)
+    if (binSlot) {
+      for (const { key, header, buffer } of binSlot.values()) {
+        // A COPY: transfer detaches, and the stash must survive a later remount
+        // (a re-tile, a dev StrictMode double-mount, a second presented copy).
+        const copy = buffer.slice()
+        iframe.contentWindow.postMessage(
+          { type: 'awi_state_binary', key, header, buffer: copy }, '*', [copy.buffer],
+        )
+      }
+    }
+    log('replayState', {
+      figId,
+      jsonKeys: slot ? slot.size : 0,
+      binaryKeys: binSlot ? binSlot.size : 0,
+      target: iframe.getAttribute('data-testid'),
+    })
+  }
+
+  function evict(figId: string): void {
+    states.current.delete(figId)
+    binaryStates.current.delete(figId)
+    iframes.current.delete(figId)
+  }
+
+  function dump(classify?: (el: HTMLIFrameElement | undefined) => string) {
+    const rows: Record<string, unknown>[] = []
+    const figIds = new Set<string>([
+      ...states.current.keys(),
+      ...binaryStates.current.keys(),
+      ...iframes.current.keys(),
+    ])
+    for (const figId of figIds) {
+      const el = iframes.current.get(figId)
+      const rect = el?.getBoundingClientRect()
+      const bin = binaryStates.current.get(figId)
+      rows.push({
+        figId,
+        jsonKeys: states.current.get(figId)?.size ?? 0,
+        binaryKeys: bin?.size ?? 0,
+        binaryKeyNames: bin ? Array.from(bin.keys()).join(',') : '',
+        registeredIn: classify ? classify(el) : (el ? 'mounted' : 'NONE'),
+        size: rect ? `${Math.round(rect.width)}x${Math.round(rect.height)}` : 'n/a',
+      })
+    }
+    return rows
+  }
+
+  return {
+    iframes, states, binaryStates,
+    registerIframe, applyState, applyBinary, replay, evict, post, dump,
+  }
+}

de_shell/js/renderer/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @de/shell-renderer — the React-side kernel shared by SpyDE, de-groundcrew and
+ * de-autopilot.
+ *
+ * What is here is the machinery every shell app needs to talk to a Python
+ * backend and put figures on screen: the core message protocol, the figure
+ * bridge, and the iframe host. Layouts, sidebars and domain UI stay in the apps
+ * — the whole point of the split is that SpyDE's MDI workspace and Ground Crew's
+ * fixed panes are different answers over the SAME registry.
+ */
+export {
+  createFigureBridge, useFigureBridge, useFigureEventForwarding,
+} from './figureBridge.react'
+export type { FigureBridge, BinaryFrame, RefLike } from './figureBridge'
+
+export { FigureFrame } from './FigureFrame'
+export type { FigureFrameProps } from './FigureFrame'
+
+export {
+  shellReducer, shellInitialState, toShellAction, LOG_MAX, STREAM_MAX,
+} from './shellState'
+export type {
+  ShellState, ShellAction, LogEntry, SubItem, EnvPhase, EnvSetupState,
+} from './shellState'
+
+export { asShellMessage } from './protocol'
+export type {
+  MsgBase, ShellMessage,
+  ReadyMessage, StatusMessage, ErrorMessage, ProgressMessage,
+  BackendExitedMessage, EnvSetupMessage,
+  FigureMessage, StateUpdateMessage, StateUpdateBinaryMessage,
+  WindowClosedMessage, WindowTitleMessage, WindowComputingMessage,
+  LogMessage, LogBackfillMessage, LogLevelMessage,
+} from './protocol'

de_shell/js/renderer/protocol.ts

@@ -0,0 +1,164 @@
+/**
+ * protocol.ts — the CORE PLOTAPP messages, shared by every shell app.
+ *
+ * The Python backend emits JSON over stdout; the Electron main process relays it
+ * to the renderer. Each message is discriminated by `type`. What is modelled
+ * here is the subset with the same meaning in SpyDE, de-groundcrew and
+ * de-autopilot — lifecycle, figures, figure state, logging, progress.
+ *
+ * Everything domain-specific (SpyDE's report/movie/drift/vectors, Ground Crew's
+ * frame stats) is the app's own union, which EXTENDS this one. That works
+ * additively because every variant carries an index signature: reading a field
+ * this file doesn't model is allowed and surfaces as `unknown`, rather than
+ * being a compile error. This types the shape the renderer relies on; it is not
+ * a schema.
+ *
+ * `backend_exited` is synthesised by @de/shell-main's backendProcess, not a real
+ * PLOTAPP line.
+ */
+
+/** Any field not explicitly modelled is still readable (as `unknown`). */
+export interface MsgBase {
+  [k: string]: unknown
+}
+
+export interface ReadyMessage extends MsgBase {
+  type: 'ready'
+}
+
+export interface StatusMessage extends MsgBase {
+  type: 'status'
+  text: string
+}
+
+export interface ErrorMessage extends MsgBase {
+  type: 'error'
+  text: string
+}
+
+/** Progress of a heavy backend action. `done >= total`, or `total <= 0`, clears. */
+export interface ProgressMessage extends MsgBase {
+  type: 'progress'
+  done: number
+  total: number
+  label?: string
+}
+
+export interface BackendExitedMessage extends MsgBase {
+  type: 'backend_exited'
+  code: number | null
+  /** Set when main synthesises this for a packaged env-setup failure, as
+   *  distinct from a plain runtime death. */
+  reason?: string
+}
+
+/** First-run Python environment setup, parsed from `uv` output by the main
+ *  process (envProgress.ts). `start`/`done` bracket the run. */
+export interface EnvSetupMessage extends MsgBase {
+  type: 'env_setup'
+  event: 'start' | 'progress' | 'done'
+  phase?: 'resolving' | 'downloading' | 'installing' | 'building' | 'torch' | 'working'
+  step?: string
+  percent?: number | null
+  raw?: string
+}
+
+/** A figure to mount. Carries EITHER inline `html` (mounted via srcdoc) or a
+ *  `file_url` served through the app's figure scheme — see the note in
+ *  FigureFrame about which and why. */
+export interface FigureMessage extends MsgBase {
+  type: 'figure'
+  window_id: number
+  fig_id: string
+  html?: string
+  file_url?: string | null
+  title?: string
+  is_navigator?: boolean
+  /** Image width/height, so a host can size the pane to the data. */
+  aspect?: number
+}
+
+/** An anyplotlib state change, forwarded into the figure iframe. */
+export interface StateUpdateMessage extends MsgBase {
+  type: 'state_update'
+  fig_id: string
+  key: string
+  value: unknown
+}
+
+/** A raw pixel frame: bytes rather than base64. `header.geom` names the panel —
+ *  load-bearing for retention, see figureBridge. */
+export interface StateUpdateBinaryMessage extends MsgBase {
+  type: 'state_update_binary'
+  fig_id: string
+  key: string
+  header?: Record<string, unknown>
+  buffer: Uint8Array
+}
+
+export interface WindowClosedMessage extends MsgBase {
+  type: 'window_closed'
+  window_id: number
+}
+
+export interface WindowTitleMessage extends MsgBase {
+  type: 'window_title'
+  window_id: number
+  title: string
+}
+
+/** Drives the floating translucent "Calculating…" chip over one window. */
+export interface WindowComputingMessage extends MsgBase {
+  type: 'window_computing'
+  window_id: number
+  computing: boolean
+}
+
+/** One application-log record streamed from the backend. `area` is the
+ *  subsystem tag the app registered (see de_shell.log_stream). */
+export interface LogMessage extends MsgBase {
+  type: 'log'
+  level: string
+  name: string
+  area: string
+  msg: string
+  time: number
+}
+
+export interface LogBackfillMessage extends MsgBase {
+  type: 'log_backfill'
+  entries: Array<Record<string, unknown>>
+}
+
+export interface LogLevelMessage extends MsgBase {
+  type: 'log_level'
+  level: string
+}
+
+/** The core union. An app extends it:
+ *
+ *     type MyMessage = ShellMessage | MyDomainMessage | …
+ */
+export type ShellMessage =
+  | ReadyMessage
+  | StatusMessage
+  | ErrorMessage
+  | ProgressMessage
+  | BackendExitedMessage
+  | EnvSetupMessage
+  | FigureMessage
+  | StateUpdateMessage
+  | StateUpdateBinaryMessage
+  | WindowClosedMessage
+  | WindowTitleMessage
+  | WindowComputingMessage
+  | LogMessage
+  | LogBackfillMessage
+  | LogLevelMessage
+
+/** Narrow a raw IPC payload to the union. The cast is the point: `type` is the
+ *  discriminator and every variant tolerates unmodelled fields, so this is a
+ *  narrowing step rather than validation. */
+export function asShellMessage(msg: Record<string, unknown>): ShellMessage {
+  return msg as unknown as ShellMessage
+}

de_shell/js/renderer/shellState.test.ts

@@ -0,0 +1,193 @@
+/**
+ * shellState.test.ts — the chrome reducer.
+ *
+ * The interesting assertions are the composition ones: an app's state extends
+ * ShellState and its reducer delegates, so the shell must (a) preserve fields it
+ * knows nothing about and (b) return the state untouched for actions it does not
+ * own — otherwise the delegation silently eats the app's own actions.
+ */
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  shellReducer, shellInitialState, toShellAction, LOG_MAX, STREAM_MAX,
+  type ShellState, type LogEntry,
+} from './shellState.ts'
+
+/** A state shaped like an app's: the shell's fields plus one of its own. */
+interface AppState extends ShellState { mine: number }
+const appState: AppState = { ...shellInitialState, mine: 42 }
+
+const entry = (msg: string): LogEntry =>
+  ({ level: 'INFO', name: 'x', area: 'a', msg, time: 0 })
+
+describe('composition', () => {
+  test('an unknown action returns the SAME state object', () => {
+    // Identity, not just equality: a new object every dispatch would re-render
+    // the whole app on any action the shell does not own.
+    const next = shellReducer(appState, { type: 'NOPE' } as never)
+    assert.equal(next, appState)
+  })
+
+  test("app fields survive an action the shell DOES own", () => {
+    const next = shellReducer(appState, { type: 'STATUS', text: 'hi' })
+    assert.equal(next.mine, 42)
+    assert.equal(next.status, 'hi')
+  })
+})
+
+describe('logs', () => {
+  test('records accumulate in order', () => {
+    let s = shellReducer(appState, { type: 'LOG', entries: [entry('a')] })
+    s = shellReducer(s, { type: 'LOG', entries: [entry('b')] })
+    assert.deepEqual(s.logEntries.map(e => e.msg), ['a', 'b'])
+  })
+
+  test('an empty batch is a no-op with no new object', () => {
+    const s = shellReducer(appState, { type: 'LOG', entries: [] })
+    assert.equal(s, appState)
+  })
+
+  test('the ring is bounded and keeps the NEWEST', () => {
+    const many = Array.from({ length: LOG_MAX + 50 }, (_, i) => entry(String(i)))
+    const s = shellReducer(appState, { type: 'LOG', entries: many })
+    assert.equal(s.logEntries.length, LOG_MAX)
+    assert.equal(s.logEntries.at(-1)!.msg, String(LOG_MAX + 49))
+  })
+
+  test('backfill REPLACES rather than appends', () => {
+    // It is a re-send of history for a freshly-opened panel; appending would
+    // double every record already shown.
+    let s = shellReducer(appState, { type: 'LOG', entries: [entry('old')] })
+    s = shellReducer(s, { type: 'LOG_BACKFILL', entries: [entry('x'), entry('y')] })
+    assert.deepEqual(s.logEntries.map(e => e.msg), ['x', 'y'])
+  })
+
+  test('clear empties the panel', () => {
+    let s = shellReducer(appState, { type: 'LOG', entries: [entry('a'), entry('b')] })
+    s = shellReducer(s, { type: 'LOG_CLEAR' })
+    assert.deepEqual(s.logEntries, [])
+  })
+
+  test('clearing an empty log changes nothing', () => {
+    // Identity, not a fresh object: a reducer that allocated on every no-op
+    // would re-render the panel for nothing.
+    assert.equal(shellReducer(appState, { type: 'LOG_CLEAR' }), appState)
+  })
+
+  test('stream lines are bounded too', () => {
+    let s: AppState = appState
+    for (let i = 0; i < STREAM_MAX + 20; i++) {
+      s = shellReducer(s, { type: 'STREAM', text: String(i), kind: 'stdout' })
+    }
+    assert.ok(s.streamLines.length <= STREAM_MAX + 1)
+    assert.equal(s.streamLines.at(-1)!.text, String(STREAM_MAX + 19))
+  })
+})
+
+describe('backend death and env setup', () => {
+  test('backend death clears the setup overlay so the two cannot stack', () => {
+    let s = shellReducer(appState, { type: 'ENV_SETUP_START' })
+    assert.ok(s.envSetup)
+    s = shellReducer(s, { type: 'BACKEND_EXITED', code: 1, reason: 'uv sync failed' })
+    assert.equal(s.envSetup, null)
+    assert.equal(s.ready, false)
+    assert.deepEqual(s.backendExited, { code: 1, reason: 'uv sync failed' })
+  })
+
+  test('progress keeps the last meaningful phase/step when a line parses to nothing', () => {
+    let s = shellReducer(appState, { type: 'ENV_SETUP_START' })
+    s = shellReducer(s, {
+      type: 'ENV_SETUP_PROGRESS', phase: 'downloading', step: 'torch', percent: 10, raw: 'a',
+    })
+    s = shellReducer(s, { type: 'ENV_SETUP_PROGRESS', percent: null, raw: 'noise' })
+    assert.equal(s.envSetup!.phase, 'downloading')
+    assert.equal(s.envSetup!.step, 'torch')
+    assert.deepEqual(s.envSetup!.lines, ['a', 'noise'])
+  })
+
+  test('progress without a preceding start still works', () => {
+    // env_setup progress can be the FIRST message a slow first launch sends.
+    const s = shellReducer(appState, {
+      type: 'ENV_SETUP_PROGRESS', percent: 5, raw: 'x',
+    })
+    assert.ok(s.envSetup)
+  })
+
+  test('done clears the overlay', () => {
+    let s = shellReducer(appState, { type: 'ENV_SETUP_START' })
+    s = shellReducer(s, { type: 'ENV_SETUP_DONE' })
+    assert.equal(s.envSetup, null)
+  })
+})
+
+describe('computing overlays and action state', () => {
+  test('a repeated computing message is a no-op with no new object', () => {
+    const on = shellReducer(appState, { type: 'WINDOW_COMPUTING', windowId: 1, computing: true })
+    const again = shellReducer(on, { type: 'WINDOW_COMPUTING', windowId: 1, computing: true })
+    assert.equal(again, on, 're-emit re-rendered every window')
+  })
+
+  test('computing toggles per window independently', () => {
+    let s = shellReducer(appState, { type: 'WINDOW_COMPUTING', windowId: 1, computing: true })
+    s = shellReducer(s, { type: 'WINDOW_COMPUTING', windowId: 2, computing: true })
+    s = shellReducer(s, { type: 'WINDOW_COMPUTING', windowId: 1, computing: false })
+    assert.deepEqual([...s.computingWindows], [2])
+  })
+
+  test('active actions add and remove per window', () => {
+    let s = shellReducer(appState, { type: 'ACTION_ACTIVE', windowId: 1, name: 'fft', active: true })
+    s = shellReducer(s, { type: 'ACTION_ACTIVE', windowId: 1, name: 'vi', active: true })
+    s = shellReducer(s, { type: 'ACTION_ACTIVE', windowId: 1, name: 'fft', active: false })
+    assert.deepEqual([...s.activeActions.get(1)!], ['vi'])
+  })
+
+  test('sub-items replace by name rather than duplicating', () => {
+    let s = shellReducer(appState, {
+      type: 'SUB_ITEM', windowId: 1, action: 'vi', name: 'r1', color: 'red', active: true,
+    })
+    s = shellReducer(s, {
+      type: 'SUB_ITEM', windowId: 1, action: 'vi', name: 'r1', color: 'blue', active: true,
+    })
+    const list = s.subItems.get(1)!.get('vi')!
+    assert.equal(list.length, 1)
+    assert.equal(list[0].color, 'blue')
+  })
+
+  test('an inactive sub-item is removed', () => {
+    let s = shellReducer(appState, {
+      type: 'SUB_ITEM', windowId: 1, action: 'vi', name: 'r1', color: 'red', active: true,
+    })
+    s = shellReducer(s, {
+      type: 'SUB_ITEM', windowId: 1, action: 'vi', name: 'r1', color: 'red', active: false,
+    })
+    assert.deepEqual(s.subItems.get(1)!.get('vi'), [])
+  })
+})
+
+describe('toShellAction', () => {
+  test('maps the chrome messages', () => {
+    assert.deepEqual(toShellAction({ type: 'status', text: 'hi' }),
+      { type: 'STATUS', text: 'hi' })
+    assert.deepEqual(toShellAction({ type: 'backend_exited', code: 2 }),
+      { type: 'BACKEND_EXITED', code: 2, reason: undefined })
+    assert.equal(toShellAction({ type: 'env_setup', event: 'start' })!.type, 'ENV_SETUP_START')
+    assert.equal(toShellAction({ type: 'env_setup', event: 'done' })!.type, 'ENV_SETUP_DONE')
+    assert.equal(
+      toShellAction({ type: 'env_setup', event: 'progress', raw: 'x' })!.type,
+      'ENV_SETUP_PROGRESS')
+  })
+
+  test('returns null for anything the app owns', () => {
+    // The contract that lets an app write `if (a) { dispatch(a); return }` and
+    // then handle the rest — a wrong non-null here would SWALLOW a domain
+    // message.
+    assert.equal(toShellAction({ type: 'frame_stats' }), null)
+    assert.equal(toShellAction({ type: 'figure' }), null)
+    assert.equal(toShellAction({ type: 'log' }), null)
+  })
+
+  test('log is deliberately NOT mapped, so hosts can batch', () => {
+    assert.equal(toShellAction({ type: 'log', msg: 'x' }), null)
+  })
+})