martty 0.2.11

package/lib/tui-overlay.js

@@ -0,0 +1,252 @@
+/** Native, semantic TUI overlays for Client Plugins. */
+
+import { Service } from '@deepseek-ai/cordis'
+import { CORDIS_METHODS } from './cordis-protocol.js'
+import { validateNodes } from './tui-slots.js'
+
+export const name = 'tui-overlay'
+export const inject = []
+
+const PROTOCOL = 0
+
+class TuiOverlayService extends Service {
+  constructor(ctx, core) {
+    super(ctx, 'tuiOverlay')
+    this.core = core
+  }
+
+  openSlider(options, handlers) {
+    return this.core.openSlider(options, handlers)
+  }
+
+  openView(options, handlers) {
+    return this.core.openView(options, handlers)
+  }
+
+  dispatch(params) {
+    return this.core.dispatch(params)
+  }
+
+  active() {
+    return this.core.active()
+  }
+
+  bindNotify(notify) {
+    return this.core.bindNotify(notify)
+  }
+}
+
+function finite(value, path) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`tuiOverlay.openSlider: ${path} must be a finite number`)
+  }
+  return value
+}
+
+function validateSlider(input) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('tuiOverlay.openSlider: options must be an object')
+  }
+  if (typeof input.id !== 'string' || input.id.length === 0) {
+    throw new Error('tuiOverlay.openSlider: id must be a non-empty string')
+  }
+  if (typeof input.title !== 'string' || input.title.length === 0) {
+    throw new Error('tuiOverlay.openSlider: title must be a non-empty string')
+  }
+  const min = finite(input.min, 'min')
+  const max = finite(input.max, 'max')
+  const step = finite(input.step, 'step')
+  const value = finite(input.value, 'value')
+  if (min >= max) throw new Error('tuiOverlay.openSlider: min must be less than max')
+  if (step <= 0) throw new Error('tuiOverlay.openSlider: step must be greater than zero')
+  const marks = input.marks === undefined ? [] : input.marks
+  if (!Array.isArray(marks)) throw new Error('tuiOverlay.openSlider: marks must be an array')
+  const validatedMarks = marks.map((mark, index) => {
+    if (mark === null || typeof mark !== 'object' || Array.isArray(mark)) {
+      throw new Error(`tuiOverlay.openSlider: marks[${index}] must be an object`)
+    }
+    const markValue = finite(mark.value, `marks[${index}].value`)
+    if (markValue < min || markValue > max) {
+      throw new Error(`tuiOverlay.openSlider: marks[${index}].value is outside the slider range`)
+    }
+    if (typeof mark.label !== 'string' || mark.label.length === 0) {
+      throw new Error(`tuiOverlay.openSlider: marks[${index}].label must be a non-empty string`)
+    }
+    if (mark.id !== undefined && (typeof mark.id !== 'string' || mark.id.length === 0)) {
+      throw new Error(`tuiOverlay.openSlider: marks[${index}].id must be a non-empty string`)
+    }
+    return {
+      value: markValue,
+      ...(mark.id === undefined ? {} : { id: mark.id }),
+      label: mark.label,
+    }
+  })
+  const snapToMarks = input.snapToMarks === true
+  if (snapToMarks && validatedMarks.length === 0) {
+    throw new Error('tuiOverlay.openSlider: snapToMarks needs at least one mark')
+  }
+  return {
+    kind: 'slider',
+    id: input.id,
+    title: input.title,
+    min,
+    max,
+    step,
+    marks: validatedMarks,
+    snapToMarks,
+    value: Math.min(max, Math.max(min, value)),
+  }
+}
+
+function validateView(input) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('tuiOverlay.openView: options must be an object')
+  }
+  if (typeof input.id !== 'string' || input.id.length === 0) {
+    throw new Error('tuiOverlay.openView: id must be a non-empty string')
+  }
+  if (typeof input.title !== 'string' || input.title.length === 0) {
+    throw new Error('tuiOverlay.openView: title must be a non-empty string')
+  }
+  return {
+    kind: 'view',
+    id: input.id,
+    title: input.title,
+    nodes: validateNodes(input.nodes, 'view.nodes'),
+  }
+}
+
+/**
+ * @param {object} ctx
+ * @param {{ notify?: (method: string, params: object) => void }} [options]
+ */
+export function installTuiOverlay(ctx, options = {}) {
+  const queue = []
+  let send = typeof options.notify === 'function' ? options.notify : undefined
+  let current = null
+
+  function emit(method, params) {
+    if (typeof send === 'function') send(method, params)
+    else queue.push({ method, params })
+  }
+
+  function bindNotify(notify) {
+    if (typeof notify !== 'function') throw new Error('tuiOverlay.bindNotify: notify must be a function')
+    send = notify
+    for (const item of queue.splice(0)) send(item.method, item.params)
+  }
+
+  function publish(overlay) {
+    emit(CORDIS_METHODS.overlayUpdate, { protocol: PROTOCOL, overlay })
+  }
+
+  function controllerFor(entry) {
+    return {
+      close() {
+        if (entry.closed) return
+        entry.closed = true
+        if (current === entry) {
+          current = null
+          publish(null)
+        }
+      },
+    }
+  }
+
+  function openSlider(options, handlers = {}) {
+    if (current !== null) {
+      throw new Error(`tuiOverlay.openSlider: overlay "${current.overlay.id}" is already open`)
+    }
+    const slider = validateSlider(options)
+    const entry = { overlay: slider, handlers, closed: false }
+    current = entry
+    publish({ ...slider, marks: slider.marks.map((mark) => ({ ...mark })) })
+    return controllerFor(entry)
+  }
+
+  function openView(options, handlers = {}) {
+    const view = validateView(options)
+    if (current !== null) {
+      if (current.overlay.kind === 'view' && current.overlay.id === view.id) {
+        current.overlay = view
+        current.handlers = handlers
+        publish(structuredClone(view))
+        return controllerFor(current)
+      }
+      throw new Error(`tuiOverlay.openView: overlay "${current.overlay.id}" is already open`)
+    }
+    const entry = { overlay: view, handlers, closed: false }
+    current = entry
+    publish(structuredClone(view))
+    return controllerFor(entry)
+  }
+
+  async function dispatch(params) {
+    if (params === null || typeof params !== 'object' || params.protocol !== PROTOCOL) {
+      throw new Error('tuiOverlay.dispatch: unsupported overlay event')
+    }
+    const entry = current
+    if (entry === null || entry.closed || params.id !== entry.overlay.id) {
+      throw new Error(`tuiOverlay.dispatch: overlay "${String(params.id)}" is not active`)
+    }
+
+    if (entry.overlay.kind === 'view') {
+      if (params.event !== 'cancel' && params.event !== 'submit') {
+        throw new Error(`tuiOverlay.dispatch: unknown view event "${String(params.event)}"`)
+      }
+      const handler = params.event === 'submit'
+        ? entry.handlers.onSubmit
+        : entry.handlers.onCancel
+      entry.closed = true
+      if (current === entry) {
+        current = null
+        publish(null)
+      }
+      return handler?.()
+    }
+
+    const slider = entry.overlay
+    const value = finite(params.value, 'event.value')
+    if (value < slider.min || value > slider.max) {
+      throw new Error('tuiOverlay.dispatch: event.value is outside the slider range')
+    }
+    slider.value = value
+    if (params.event === 'change') {
+      return entry.handlers.onChange?.(value)
+    }
+    if (params.event !== 'submit' && params.event !== 'cancel') {
+      throw new Error(`tuiOverlay.dispatch: unknown event "${String(params.event)}"`)
+    }
+    const mark = slider.marks.reduce((nearest, candidate) => {
+      if (nearest === undefined) return candidate
+      return Math.abs(candidate.value - value) < Math.abs(nearest.value - value)
+        ? candidate
+        : nearest
+    }, undefined)
+    const handler = params.event === 'submit'
+      ? entry.handlers.onSubmit
+      : entry.handlers.onCancel
+    const controller = { close: () => {} }
+    entry.closed = true
+    if (current === entry) {
+      current = null
+      publish(null)
+    }
+    return handler?.(value, mark, controller)
+  }
+
+  function active() {
+    return current === null ? null : structuredClone(current.overlay)
+  }
+
+  const core = { openSlider, openView, dispatch, active, bindNotify }
+  const service = typeof ctx.provide === 'function'
+    ? new TuiOverlayService(ctx, core)
+    : { openSlider, openView, dispatch, active, bindNotify }
+  if (typeof ctx.provide !== 'function') ctx.tuiOverlay = service
+  return service
+}
+
+export function apply(ctx) {
+  installTuiOverlay(ctx)
+}

package/lib/tui-slots.js

@@ -0,0 +1,351 @@
+/**
+ * Structured TUI shell slots. Plugins contribute TuiNode trees; the service
+ * owns validation, aggregation, lifecycle, and compositor snapshots.
+ */
+
+import { Service } from '@deepseek-ai/cordis'
+import { CORDIS_METHODS } from './cordis-protocol.js'
+
+export const name = 'tui-slots'
+export const inject = []
+
+export const SLOT_NAMES = Object.freeze([
+  'chrome.right',
+  'conversation.input.dock',
+  'conversation.composer.dock',
+])
+
+const SLOT_DEFINITIONS = Object.freeze({
+  'chrome.right': Object.freeze({ kind: 'list', scope: 'root' }),
+  'conversation.input.dock': Object.freeze({ kind: 'list', scope: 'session' }),
+  'conversation.composer.dock': Object.freeze({ kind: 'list', scope: 'session' }),
+})
+
+class TuiSlotsService extends Service {
+  constructor(ctx, core) {
+    super(ctx, 'tuiSlots')
+    this.core = core
+  }
+
+  inject(slot, callback) {
+    return this.core.inject(this.ctx, slot, callback)
+  }
+
+  register(options, nodes) {
+    return this.core.register(this.ctx, options, nodes)
+  }
+
+  list() {
+    return this.core.list()
+  }
+
+  bindNotify(notify) {
+    return this.core.bindNotify(notify)
+  }
+}
+
+const PROTOCOL = 0
+const THEME_TOKENS = new Set([
+  'bg', 'surface', 'panel', 'fg', 'fg_secondary', 'fg_tertiary', 'caption',
+  'brand', 'brand_soft', 'bubble_bg', 'bubble_fg', 'border', 'code_bg', 'ok',
+  'warn', 'err', 'hint', 'chip_bg',
+])
+
+const NODE_FIELDS = Object.freeze({
+  group: { required: ['id', 'kind', 'children'], optional: ['title', 'tone'] },
+  markdown: { required: ['id', 'kind', 'text'], optional: ['streaming'] },
+  reasoning: { required: ['id', 'kind', 'text', 'done'], optional: ['seconds'] },
+  user: { required: ['id', 'kind', 'text'], optional: ['queued'] },
+  generic: { required: ['id', 'kind', 'title', 'body'], optional: ['status', 'action'] },
+  terminal: { required: ['id', 'kind', 'title', 'body'], optional: ['exit'] },
+  diff: { required: ['id', 'kind', 'title', 'unified'], optional: ['path'] },
+  image: { required: ['id', 'kind', 'name', 'mime'], optional: ['dataBase64'] },
+  notice: { required: ['id', 'kind', 'level', 'text'], optional: [] },
+  unknown: { required: ['id', 'kind', 'want'], optional: ['title', 'detail'] },
+})
+
+function object(value, path) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`tuiSlots: ${path} must be an object`)
+  }
+  return value
+}
+
+function string(value, path, allowEmpty = true) {
+  if (typeof value !== 'string' || (!allowEmpty && value.length === 0)) {
+    throw new Error(`tuiSlots: ${path} must be ${allowEmpty ? 'a string' : 'a non-empty string'}`)
+  }
+}
+
+function optionalString(value, path) {
+  if (value !== undefined) string(value, path)
+}
+
+function optionalBoolean(value, path) {
+  if (value !== undefined && typeof value !== 'boolean') {
+    throw new Error(`tuiSlots: ${path} must be a boolean`)
+  }
+}
+
+function optionalAction(value, path) {
+  if (value === undefined) return
+  object(value, path)
+  const extras = Object.keys(value).filter((key) => !['kind', 'name', 'args'].includes(key))
+  if (extras.length > 0) throw new Error(`tuiSlots: ${path} has unknown field(s) ${extras.join(', ')}`)
+  if (value.kind !== 'command') throw new Error(`tuiSlots: ${path}.kind must be command`)
+  string(value.name, `${path}.name`, false)
+  optionalString(value.args, `${path}.args`)
+}
+
+function validateNode(node, path, ids) {
+  object(node, path)
+  string(node.kind, `${path}.kind`, false)
+  const shape = NODE_FIELDS[node.kind]
+  if (shape === undefined) throw new Error(`tuiSlots: ${path}.kind "${node.kind}" is not supported`)
+  const fields = new Set([...shape.required, ...shape.optional])
+  const extras = Object.keys(node).filter((key) => !fields.has(key))
+  if (extras.length > 0) throw new Error(`tuiSlots: ${path} has unknown field(s) ${extras.join(', ')}`)
+  for (const field of shape.required) {
+    if (!Object.hasOwn(node, field)) throw new Error(`tuiSlots: ${path}.${field} is required`)
+  }
+  string(node.id, `${path}.id`, false)
+  if (ids.has(node.id)) throw new Error(`tuiSlots: duplicate node id "${node.id}"`)
+  ids.add(node.id)
+
+  switch (node.kind) {
+    case 'group':
+      optionalString(node.title, `${path}.title`)
+      if (node.tone !== undefined && !THEME_TOKENS.has(node.tone)) {
+        throw new Error(`tuiSlots: ${path}.tone must be a theme token`)
+      }
+      node.children = validateNodes(node.children, `${path}.children`, ids)
+      break
+    case 'markdown':
+      string(node.text, `${path}.text`)
+      optionalBoolean(node.streaming, `${path}.streaming`)
+      break
+    case 'reasoning':
+      string(node.text, `${path}.text`)
+      if (typeof node.done !== 'boolean') throw new Error(`tuiSlots: ${path}.done must be a boolean`)
+      if (node.seconds !== undefined && (typeof node.seconds !== 'number' || node.seconds < 0)) {
+        throw new Error(`tuiSlots: ${path}.seconds must be a non-negative number`)
+      }
+      break
+    case 'user':
+      string(node.text, `${path}.text`)
+      optionalBoolean(node.queued, `${path}.queued`)
+      break
+    case 'generic':
+      string(node.title, `${path}.title`)
+      string(node.body, `${path}.body`)
+      if (node.status !== undefined && !['running', 'ok', 'err'].includes(node.status)) {
+        throw new Error(`tuiSlots: ${path}.status must be running, ok, or err`)
+      }
+      optionalAction(node.action, `${path}.action`)
+      break
+    case 'terminal':
+      string(node.title, `${path}.title`)
+      string(node.body, `${path}.body`)
+      if (node.exit !== undefined && node.exit !== null && !Number.isInteger(node.exit)) {
+        throw new Error(`tuiSlots: ${path}.exit must be an integer or null`)
+      }
+      break
+    case 'diff':
+      string(node.title, `${path}.title`)
+      string(node.unified, `${path}.unified`)
+      optionalString(node.path, `${path}.path`)
+      break
+    case 'image':
+      string(node.name, `${path}.name`)
+      string(node.mime, `${path}.mime`)
+      optionalString(node.dataBase64, `${path}.dataBase64`)
+      break
+    case 'notice':
+      string(node.text, `${path}.text`)
+      if (!['info', 'warn', 'error'].includes(node.level)) {
+        throw new Error(`tuiSlots: ${path}.level must be info, warn, or error`)
+      }
+      break
+    case 'unknown':
+      string(node.want, `${path}.want`, false)
+      optionalString(node.title, `${path}.title`)
+      optionalString(node.detail, `${path}.detail`)
+      break
+    default:
+  }
+  return { ...node }
+}
+
+export function validateNodes(nodes, path = 'nodes', ids = new Set()) {
+  if (!Array.isArray(nodes)) throw new Error(`tuiSlots: ${path} must be an array`)
+  return nodes.map((node, index) => validateNode(structuredClone(node), `${path}[${index}]`, ids))
+}
+
+function namespaceNode(node, contributionId) {
+  const namespaced = { ...node, id: `${contributionId}:${node.id}` }
+  if (node.kind === 'group') {
+    namespaced.children = node.children.map((child) => namespaceNode(child, contributionId))
+  }
+  return namespaced
+}
+
+function disposerOf(value) {
+  if (typeof value === 'function') return value
+  if (value !== null && typeof value === 'object' && typeof value.dispose === 'function') {
+    return () => value.dispose()
+  }
+  return () => {}
+}
+
+/** Install the declared root-slot registry on a Cordis client context. */
+export function installTuiSlots(ctx, options = {}) {
+  const contributions = new Map()
+  let nextSequence = 0
+  const revisions = new Map(SLOT_NAMES.map((slot) => [slot, 0]))
+  let send = typeof options.notify === 'function' ? options.notify : undefined
+  const queued = new Map()
+
+  function snapshot(slot) {
+    const nodes = [...contributions.values()]
+      .filter((entry) => entry.slot === slot)
+      .sort((left, right) => left.order - right.order || left.sequence - right.sequence)
+      .flatMap((entry) => entry.nodes.map((node) => namespaceNode(node, entry.id)))
+    const revision = (revisions.get(slot) ?? 0) + 1
+    revisions.set(slot, revision)
+    return { protocol: PROTOCOL, slot, rev: revision, nodes }
+  }
+
+  function publish(slot) {
+    const params = snapshot(slot)
+    if (typeof send === 'function') send(CORDIS_METHODS.slotsUpdate, params)
+    else queued.set(slot, params)
+  }
+
+  function bindNotify(notify) {
+    if (typeof notify !== 'function') throw new Error('tuiSlots.bindNotify: notify must be a function')
+    send = notify
+    for (const slot of SLOT_NAMES) {
+      const params = queued.get(slot)
+      if (params === undefined) continue
+      queued.delete(slot)
+      send(CORDIS_METHODS.slotsUpdate, params)
+    }
+  }
+
+  function register(effectCtx, options, nodes) {
+    object(options, 'register options')
+    const definition = SLOT_DEFINITIONS[options.name]
+    if (definition === undefined) {
+      throw new Error(
+        `tuiSlots.register: slot "${String(options.name)}" is not declared; use ${SLOT_NAMES.join(' or ')}`,
+      )
+    }
+    string(options.id, 'register options.id', false)
+    const extras = Object.keys(options).filter((key) => !['name', 'id', 'order'].includes(key))
+    if (extras.length > 0) throw new Error(`tuiSlots.register: unknown option(s) ${extras.join(', ')}`)
+    const order = options.order ?? 0
+    if (typeof order !== 'number' || !Number.isFinite(order)) {
+      throw new Error('tuiSlots.register: order must be a finite number')
+    }
+    const key = `${options.name}\u0000${options.id}`
+    if (contributions.has(key)) {
+      throw new Error(
+        `tuiSlots.register: contribution "${options.id}" is already registered in ${options.name}`,
+      )
+    }
+    if (definition.kind === 'single'
+      && [...contributions.values()].some((entry) => entry.slot === options.name)) {
+      throw new Error(`tuiSlots.register: single slot "${options.name}" is already occupied`)
+    }
+    const entry = {
+      key,
+      slot: options.name,
+      id: options.id,
+      order,
+      sequence: nextSequence++,
+      nodes: validateNodes(nodes),
+      active: false,
+    }
+    const setup = () => {
+      if (definition.kind === 'single'
+        && [...contributions.values()].some((candidate) => candidate.slot === entry.slot)) {
+        throw new Error(`tuiSlots.register: single slot "${entry.slot}" is already occupied`)
+      }
+      entry.active = true
+      contributions.set(entry.key, entry)
+      publish(entry.slot)
+      return () => {
+        if (!entry.active) return
+        entry.active = false
+        if (contributions.get(entry.key) === entry) contributions.delete(entry.key)
+        publish(entry.slot)
+      }
+    }
+    const releaseEffect = typeof effectCtx.effect === 'function'
+      ? effectCtx.effect(setup, `tuiSlots.register(${JSON.stringify(entry.id)})`)
+      : setup()
+    let disposed = false
+    const controller = {
+      update(nextNodes) {
+        if (disposed || !entry.active) throw new Error(`tuiSlots: contribution "${entry.id}" is disposed`)
+        entry.nodes = validateNodes(nextNodes)
+        publish(entry.slot)
+      },
+      dispose() {
+        if (disposed) return
+        disposed = true
+        return releaseEffect?.()
+      },
+    }
+    return controller
+  }
+
+  function inject(effectCtx, slot, callback) {
+    if (SLOT_DEFINITIONS[slot] === undefined) {
+      throw new Error(
+        `tuiSlots.inject: slot "${String(slot)}" is not declared; use ${SLOT_NAMES.join(' or ')}`,
+      )
+    }
+    if (typeof callback !== 'function') throw new Error('tuiSlots.inject: callback must be a function')
+    const setup = () => disposerOf(callback())
+    const releaseEffect = typeof effectCtx.effect === 'function'
+      ? effectCtx.effect(setup, `tuiSlots.inject(${JSON.stringify(slot)})`)
+      : setup()
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      return releaseEffect?.()
+    }
+  }
+
+  function list() {
+    return SLOT_NAMES.map((slot) => ({
+      name: slot,
+      ...SLOT_DEFINITIONS[slot],
+      occupants: [...contributions.values()]
+        .filter((entry) => entry.slot === slot)
+        .map(({ id, order }) => ({ id, order })),
+    }))
+  }
+
+  const core = { inject, register, list, bindNotify }
+  const service = typeof ctx.provide === 'function'
+    ? new TuiSlotsService(ctx, core)
+    : {
+        inject(slot, callback) {
+          return inject(ctx, slot, callback)
+        },
+        register(options, nodes) {
+          return register(ctx, options, nodes)
+        },
+        list,
+        bindNotify,
+      }
+  if (typeof ctx.provide !== 'function') ctx.tuiSlots = service
+  return service
+}
+
+export function apply(ctx) {
+  installTuiSlots(ctx)
+}