acrylblends 0.2.0 → 0.3.0

package/plugins/acryl-router-http/tests/stream.spec.ts

@@ -0,0 +1,133 @@
+/**
+ * Server-sent events end to end (spec 046, M5): the actual DSH `webServer`, the router, the HTTP adapter and the state
+ * service. A browser-shaped `fetch` reads the stream; a change in the Host reaches it; a disconnect and a plugin unload both
+ * end it and leave nothing subscribed.
+ */
+
+import { request as httpRequest } from 'node:http'
+import { Context } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { apply as stateApply, name as stateName } from '../../acryl-state/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply as httpApply, inject as httpInject, name as httpName } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function until(check: () => boolean, label: string): Promise<void> {
+  for (let i = 0; i < 300; i += 1) { if (check()) return; await settle(10) }
+  throw new Error(`timed out waiting for: ${label}`)
+}
+
+async function stack(): Promise<{ ctx: Context, base: string }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name: httpName, inject: httpInject, apply: httpApply })
+  ctx.plugin({ name: stateName, apply: stateApply })
+  const web = ctx as unknown as { webServer?: { port: number } }
+  await until(() => web.webServer?.port !== undefined && (ctx as unknown as { routerHttp?: unknown }).routerHttp !== undefined && (ctx as unknown as { state?: unknown }).state !== undefined, 'the stack')
+  await settle(30)
+  return { ctx, base: `http://127.0.0.1:${String(web.webServer!.port)}` }
+}
+
+/** Collect SSE records from a fetch response until `count` arrived. */
+async function read(reader: ReadableStreamDefaultReader<Uint8Array>, count: number): Promise<string[]> {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  const out: string[] = []
+  while (out.length < count) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += decoder.decode(value, { stream: true })
+    for (let at = buffer.indexOf('\n\n'); at !== -1; at = buffer.indexOf('\n\n')) {
+      out.push(buffer.slice(0, at))
+      buffer = buffer.slice(at + 2)
+    }
+  }
+  return out
+}
+
+describe('server-sent events through the real stack', () => {
+  it('streams the value now and each change to a real HTTP client, with the stream headers', async () => {
+    const { ctx, base } = await stack()
+    const cell = ctx.state.cell<{ n: number }>('app.counter', { n: 0 })
+    const response = await fetch(`${base}/api/state/app.counter/events`)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    const reader = response.body!.getReader()
+    const first = read(reader, 3)
+    await settle(20)
+    cell.set({ n: 1 })
+    cell.set({ n: 2 })
+    expect(await first).toEqual(['event: value\ndata: {"n":0}', 'event: value\ndata: {"n":1}', 'event: value\ndata: {"n":2}'])
+    await reader.cancel()
+  })
+
+  it('stops pushing to a client that disconnected: the cell keeps no subscriber for it', async () => {
+    const { ctx, base } = await stack()
+    const cell = ctx.state.cell<number>('app.n', 0)
+    const controller = new AbortController()
+    const response = await fetch(`${base}/api/state/app.n/events`, { signal: controller.signal })
+    const reader = response.body!.getReader()
+    await read(reader, 1)
+    let seenByProbe = 0
+    // While connected, a change reaches the stream; count the cell's own subscribers through a counting wrapper.
+    controller.abort()
+    await reader.cancel().catch(() => undefined)
+    await settle(50)
+    const stop = cell.subscribe(() => { seenByProbe += 1 })
+    cell.set(1)
+    stop()
+    expect(seenByProbe).toBe(1)
+    // The disconnect released the stream: the router has no request left in flight to abort at disposal.
+    const started = Date.now()
+    await ctx.fiber.dispose()
+    contexts.length = 0
+    expect(Date.now() - started).toBeLessThan(1500)
+  })
+
+  it('ends an open stream when the state plugin unloads', async () => {
+    const { ctx, base } = await stack()
+    ctx.state.cell<number>('app.n', 0)
+    const response = await fetch(`${base}/api/state/app.n/events`)
+    const reader = response.body!.getReader()
+    await read(reader, 1)
+    const ended = reader.read()
+    const routerFiber = [...[...ctx.registry.values()].find(runtime => runtime.name === routerName)!.fibers][0]!
+    await routerFiber.dispose()
+    await expect(ended).resolves.toMatchObject({ done: true })
+  })
+})
+
+describe('the loopback guard over real HTTP', () => {
+  /** A raw request, so the test chooses the Host header (fetch would set its own). */
+  function raw(port: number, path: string, headers: Record<string, string>): Promise<{ status: number, body: string }> {
+    return new Promise((resolve, reject) => {
+      const req = httpRequest({ host: '127.0.0.1', port, path, headers }, res => {
+        let body = ''
+        res.on('data', chunk => { body += String(chunk) })
+        res.on('end', () => { resolve({ status: res.statusCode ?? 0, body }) })
+      })
+      req.on('error', reject)
+      req.end()
+    })
+  }
+
+  it('serves the state routes to this machine and refuses a request that names another host or is marked cross-site', async () => {
+    const { ctx, base } = await stack()
+    ctx.state.cell<number>('app.n', 3)
+    const port = Number(new URL(base).port)
+    const ok = await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port)}` })
+    expect(ok.status).toBe(200)
+    expect(JSON.parse(ok.body)).toEqual({ key: 'app.n', value: 3 })
+    expect((await raw(port, '/api/state/app.n', { host: 'evil.example' })).status).toBe(403)
+    expect((await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port + 1)}` })).status).toBe(403)
+    expect((await raw(port, '/api/state/app.n', { host: `127.0.0.1:${String(port)}`, 'sec-fetch-site': 'cross-site' })).status).toBe(403)
+  })
+})

package/plugins/acryl-router-http/tests/surfaces.spec.ts

@@ -0,0 +1,99 @@
+/**
+ * One plugin, two compositions (spec 046, M3): the same `apply` runs in a Web or Desktop composition (the DSH webServer,
+ * the router and the HTTP adapter) and in a terminal composition (the router alone, no server at all). The routes are
+ * registered once, in `apply`; serving them over HTTP is the optional part, requested through an inner `inject`. The
+ * assertions compare what a browser receives with what the terminal's in-process call receives.
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import WebServer from '@deepseek-ai/dsh-host-webserver'
+import { apply as routerApply, name as routerName } from '../../acryl-router/src/index.ts'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply as httpApply, inject as httpInject, name as httpName } from '../src/index.ts'
+
+const contexts: Context[] = []
+const settle = (ms = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, ms))
+afterEach(async () => {
+  while (contexts.length > 0) await contexts.pop()?.fiber.dispose()
+})
+
+async function until(check: () => boolean, label: string): Promise<void> {
+  for (let i = 0; i < 300; i += 1) { if (check()) return; await settle(10) }
+  throw new Error(`timed out waiting for: ${label}`)
+}
+
+/** A capability as a plugin author writes it: routes in `apply`, HTTP only if an adapter happens to be present. */
+const notes = {
+  name: 'notes-demo',
+  inject: ['router'],
+  apply(ctx: Context): void {
+    const store = new Map<string, string>()
+    ctx.router.post('/api/notes/:id', async c => {
+      const text = await c.req.text()
+      store.set(c.params['id'] ?? '', text)
+      return c.json({ id: c.params['id'], saved: text.length }, 201)
+    })
+    ctx.router.get('/api/notes/:id', c => {
+      const text = store.get(c.params['id'] ?? '')
+      return text === undefined ? c.json({ error: 'not found' }, 404) : c.json({ id: c.params['id'], text })
+    })
+    ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/api/notes') })
+  },
+}
+
+/** Web or Desktop: a loopback webServer, the router and the adapter. */
+async function webComposition(): Promise<{ ctx: Context, base: string }> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin(WebServer, { host: '127.0.0.1', port: 0 } as never)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  ctx.plugin({ name: httpName, inject: httpInject, apply: httpApply })
+  const web = ctx as unknown as { webServer?: { port: number } }
+  await until(() => web.webServer?.port !== undefined && (ctx as unknown as { routerHttp?: unknown }).routerHttp !== undefined, 'the web composition')
+  ctx.plugin(notes)
+  await settle(30)
+  return { ctx, base: `http://127.0.0.1:${String(web.webServer!.port)}` }
+}
+
+/** Terminal: the router only. No server, no adapter, nothing listening. */
+async function terminalComposition(): Promise<Context> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  ctx.plugin({ name: routerName, apply: routerApply }, { trailingSlash: 'strict' })
+  await settle(20)
+  ctx.plugin(notes)
+  await settle(20)
+  return ctx
+}
+
+async function snapshot(response: Response): Promise<{ status: number, type: string | null, body: unknown }> {
+  return { status: response.status, type: response.headers.get('content-type'), body: await response.json() }
+}
+
+describe('the same capability on every surface', () => {
+  it('answers a browser over HTTP and the terminal in process with the same status, headers and body', async () => {
+    const web = await webComposition()
+    const terminal = await terminalComposition()
+
+    const viaHttp = [
+      await snapshot(await fetch(`${web.base}/api/notes/a`)),
+      await snapshot(await fetch(`${web.base}/api/notes/a`, { method: 'POST', body: 'hello' })),
+      await snapshot(await fetch(`${web.base}/api/notes/a`)),
+    ]
+    const router = (terminal as unknown as { router: { fetch(request: Request): Promise<Response> } }).router
+    const inProcess = [
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a'))),
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a', { method: 'POST', body: 'hello' }))),
+      await snapshot(await router.fetch(new Request('http://acryl.test/api/notes/a'))),
+    ]
+
+    expect(inProcess).toEqual(viaHttp)
+    expect(viaHttp.map(step => step.status)).toEqual([404, 201, 200])
+  })
+
+  it('opens no socket in the terminal composition: nothing in that context is a server', async () => {
+    const terminal = await terminalComposition()
+    expect((terminal as unknown as { webServer?: unknown }).webServer).toBeUndefined()
+    expect((terminal as unknown as { routerHttp?: unknown }).routerHttp).toBeUndefined()
+  })
+})

package/plugins/acryl-router-http/upstream.json

@@ -0,0 +1,22 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "path": "plugins/acryl-router-http",
+    "commit": "11fed295161c0282d144b5ac62616988b58d8189"
+  },
+  "vendored": [
+    "src",
+    "tests",
+    "LICENSE"
+  ],
+  "rewrittenSpecifiers": 6,
+  "digest": "sha256:6a79e85a11bf61a13604736ef9776f878a024ef19e1282481bdfe13343916bc4",
+  "testsNotRun": {
+    "tests/adapter.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server); acryl-node-server has its own tests",
+    "tests/stream.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server)",
+    "tests/surfaces.spec.ts": "needs @deepseek-ai/dsh-host-webserver (the DSH web server)"
+  },
+  "notice": [
+    "LICENSE"
+  ]
+}

package/plugins/acryl-state/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-state/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "acryl-state",
+  "description": "Observable cells and derived cells, shared state with JSON and server-sent event routes on the router. Vendored from ACRYL.",
+  "requires": ["acryl-router"],
+  "inject": ["router"],
+  "provides": ["state"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4"
+  },
+  "mount": "root.plugin(state); ctx.state.cell('todos.count', 0), then count.update((n) => n + 1)",
+  "omit": ["src/react.ts"]
+}

package/plugins/acryl-state/src/cell.ts

@@ -0,0 +1,67 @@
+/**
+ * Observable cells: the reactive core of the state service, with no Cordis and no DOM. A cell holds one value, tells its
+ * subscribers when it changes, and can be derived from other cells. The shape is a writable cell and a derived cell
+ * (spec 046, M5): small enough to read in one sitting, and the same cell serves a React hook, a terminal component and a
+ * server-sent stream.
+ */
+
+export type Listener<T> = (value: T, previous: T) => void
+
+export interface ReadonlyCell<T> {
+  readonly key: string
+  get(): T
+  /** Call `listener` after every change (never for a set to an equal value). Returns the unsubscribe function. */
+  subscribe(listener: Listener<T>): () => void
+}
+
+export interface Cell<T> extends ReadonlyCell<T> {
+  set(value: T): void
+  update(change: (current: T) => T): void
+}
+
+type ErrorSink = (error: unknown) => void
+
+/** A writable cell. `report` receives anything a listener throws; one failing listener never blocks the others. */
+export function createCell<T>(key: string, initial: T, report: ErrorSink = () => undefined): Cell<T> {
+  let value = initial
+  const listeners = new Set<Listener<T>>()
+  const set = (next: T): void => {
+    if (Object.is(next, value)) return
+    const previous = value
+    value = next
+    for (const listener of [...listeners]) {
+      try { listener(next, previous) } catch (error) { report(error) }
+    }
+  }
+  return {
+    key,
+    get: () => value,
+    set,
+    update: change => { set(change(value)) },
+    subscribe: listener => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+  }
+}
+
+type Values<D extends readonly ReadonlyCell<unknown>[]> = { [K in keyof D]: D[K] extends ReadonlyCell<infer V> ? V : never }
+
+/**
+ * A read-only cell computed from other cells and recomputed whenever one of them changes. `dispose` detaches it from its
+ * inputs; after that it keeps its last value.
+ */
+export function createDerived<D extends readonly ReadonlyCell<unknown>[], T>(
+  key: string,
+  inputs: D,
+  compute: (...values: Values<D>) => T,
+  report: ErrorSink = () => undefined,
+): { readonly cell: ReadonlyCell<T>, readonly dispose: () => void } {
+  const read = (): T => compute(...(inputs.map(input => input.get()) as unknown as Values<D>))
+  const inner = createCell<T>(key, read(), report)
+  const stops = inputs.map(input => input.subscribe(() => { inner.set(read()) }))
+  return {
+    cell: { key, get: inner.get, subscribe: inner.subscribe },
+    dispose: () => { for (const stop of stops) stop() },
+  }
+}

package/plugins/acryl-state/src/index.ts

@@ -0,0 +1,3 @@
+export { State, apply, name } from './service.ts'
+export { createCell, createDerived } from './cell.ts'
+export type { Cell, Listener, ReadonlyCell } from './cell.ts'

package/plugins/acryl-state/src/react.ts

@@ -0,0 +1,11 @@
+/**
+ * The React binding: one hook that reads a cell and re-renders when it changes. `useSyncExternalStore` is React's own
+ * contract for exactly this, so it is tear-free under concurrent rendering. Import from `acryl-state/react`.
+ */
+
+import { useSyncExternalStore } from 'react'
+import type { ReadonlyCell } from './cell.ts'
+
+export function useCell<T>(cell: ReadonlyCell<T>): T {
+  return useSyncExternalStore(listener => cell.subscribe(listener), cell.get, cell.get)
+}

package/plugins/acryl-state/src/service.ts

@@ -0,0 +1,101 @@
+/**
+ * The ACRYL state service (`ctx.state`): observable cells owned by plugins. A cell created from a plugin's context is removed
+ * when that plugin unloads, so a surface never keeps a value alive for a plugin that is gone. In process the cells are read
+ * and subscribed to directly (the terminal UI); with a router present they are also readable as JSON and streamable as
+ * server-sent events (Web and Desktop), read-only: only the Host plugin that owns a cell writes it.
+ */
+
+import { Context, Service } from '@deepseek-ai/cordis'
+import type { RouteContext } from '../../acryl-router/src/index.ts'
+import { streamSSE } from '../../acryl-router/src/helpers/index.ts'
+import { loopbackOnly } from '../../acryl-router/src/middleware/index.ts'
+import { createCell, createDerived, type Cell, type ReadonlyCell } from './cell.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    state: State
+  }
+}
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-state'
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/
+
+export class State extends Service {
+  private readonly cells = new Map<string, ReadonlyCell<unknown>>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'state')
+  }
+
+  private claim(key: string): void {
+    if (!KEY_PATTERN.test(key)) throw new TypeError(`acryl-state: key "${key}" must be dotted lowercase words, like "market.sources"`)
+    if (this.cells.has(key)) throw new Error(`acryl-state: key "${key}" is already in use`)
+  }
+
+  private report = (error: unknown): void => {
+    this.ctx.logger.error(`acryl-state: a subscriber failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  /** Create a writable cell owned by the calling plugin. The key must be new. */
+  cell<T>(key: string, initial: T): Cell<T> {
+    this.claim(key)
+    const cell = createCell(key, initial, this.report)
+    this.cells.set(key, cell as ReadonlyCell<unknown>)
+    this.ctx.effect(() => () => { this.cells.delete(key) }, `acryl-state: cell ${key}`)
+    return cell
+  }
+
+  /** Create a read-only cell computed from other cells, owned by the calling plugin. */
+  derive<D extends readonly ReadonlyCell<unknown>[], T>(
+    key: string,
+    inputs: D,
+    compute: (...values: { [K in keyof D]: D[K] extends ReadonlyCell<infer V> ? V : never }) => T,
+  ): ReadonlyCell<T> {
+    this.claim(key)
+    const derived = createDerived(key, inputs, compute, this.report)
+    this.cells.set(key, derived.cell as ReadonlyCell<unknown>)
+    this.ctx.effect(() => () => { derived.dispose(); this.cells.delete(key) }, `acryl-state: derived ${key}`)
+    return derived.cell
+  }
+
+  /** A cell by key, if one is live. */
+  find<T = unknown>(key: string): ReadonlyCell<T> | undefined {
+    return this.cells.get(key) as ReadonlyCell<T> | undefined
+  }
+
+  keys(): string[] {
+    return [...this.cells.keys()].sort()
+  }
+
+  /**
+   * The current value of `key` as a server-sent event stream: the value now, then one event per change, until the request is aborted, the client
+   * cancels, or the router is disposed. `streamSSE` holds the request in flight until then, so the router waits for the stream.
+   */
+  stream(key: string, c: RouteContext): Response | undefined {
+    const cell = this.find(key)
+    if (cell === undefined) return undefined
+    return streamSSE(c, stream => {
+      stream.send(cell.get(), { event: 'value' })
+      return cell.subscribe(value => { stream.send(value, { event: 'value' }) })
+    })
+  }
+}
+
+export function apply(ctx: Context): void {
+  const state = new State(ctx)
+  // The same cells on the router, read-only, for any surface; present only where a router is. A request over a socket must come from this machine to this
+  // app; the terminal calls the router in process and is the host's own code.
+  ctx.inject(['router'], inner => {
+    const api = inner.router.group('/api/state', loopbackOnly({ inProcess: 'allow' }))
+    api.get('/', c => c.json({ keys: state.keys() }))
+    api.get('/:key', c => {
+      const cell = state.find(c.param('key') ?? '')
+      return cell === undefined ? c.json({ error: 'no such state' }, 404) : c.json({ key: cell.key, value: cell.get() })
+    })
+    api.get('/:key/events', c => state.stream(c.param('key') ?? '', c) ?? c.json({ error: 'no such state' }, 404))
+    // Over HTTP only where an adapter exists (Web and Desktop); the terminal needs none.
+    inner.inject(['routerHttp'], http => { http.routerHttp.mount('/api/state') })
+  })
+}

package/plugins/acryl-state/tests/cell.spec.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createCell, createDerived } from '../src/cell.ts'
+
+describe('cells', () => {
+  it('holds a value, notifies on change with the previous value, and ignores a set to an equal value', () => {
+    const cell = createCell('a.b', 1)
+    const seen: Array<[number, number]> = []
+    cell.subscribe((value, previous) => seen.push([value, previous]))
+    cell.set(2)
+    cell.set(2)
+    cell.update(n => n + 1)
+    expect(cell.get()).toBe(3)
+    expect(seen).toEqual([[2, 1], [3, 2]])
+  })
+
+  it('stops notifying after unsubscribe, and unsubscribing twice is harmless', () => {
+    const cell = createCell('a', 0)
+    const listener = vi.fn()
+    const stop = cell.subscribe(listener)
+    cell.set(1)
+    stop()
+    stop()
+    cell.set(2)
+    expect(listener).toHaveBeenCalledTimes(1)
+  })
+
+  it('isolates a failing subscriber: the others still run and the error is reported', () => {
+    const report = vi.fn()
+    const cell = createCell('a', 0, report)
+    const after = vi.fn()
+    cell.subscribe(() => { throw new Error('boom') })
+    cell.subscribe(after)
+    cell.set(1)
+    expect(after).toHaveBeenCalledWith(1, 0)
+    expect(report).toHaveBeenCalledTimes(1)
+  })
+
+  it('lets a subscriber unsubscribe itself while being notified', () => {
+    const cell = createCell('a', 0)
+    const calls: number[] = []
+    const stop = cell.subscribe(value => { calls.push(value); stop() })
+    cell.subscribe(value => calls.push(value * 10))
+    cell.set(1)
+    cell.set(2)
+    expect(calls).toEqual([1, 10, 20])
+  })
+})
+
+describe('derived cells', () => {
+  it('recomputes from its inputs, notifies only when its own value changes, and detaches on dispose', () => {
+    const a = createCell('a', 2)
+    const b = createCell('b', 3)
+    const { cell: sum, dispose } = createDerived('sum', [a, b] as const, (x, y) => x + y)
+    const seen: number[] = []
+    sum.subscribe(value => seen.push(value))
+    expect(sum.get()).toBe(5)
+    a.set(10)
+    b.set(1)
+    expect(seen).toEqual([13, 11])
+    const parity = createDerived('parity', [a] as const, x => x % 2 === 0).cell
+    const flips: boolean[] = []
+    parity.subscribe(value => flips.push(value))
+    a.set(12)
+    a.set(14)
+    expect(flips).toEqual([])
+    dispose()
+    a.set(100)
+    // Detached: it keeps the last value it computed (14 + 1), not 100 + 1.
+    expect(sum.get()).toBe(15)
+  })
+})

package/plugins/acryl-state/tests/react.spec.ts

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+import { act, cleanup, render } from '@testing-library/react'
+import { createElement } from 'react'
+import { afterEach, describe, expect, it } from 'vitest'
+import { createCell } from '../src/cell.ts'
+import { useCell } from '../src/react.ts'
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+afterEach(cleanup)
+
+function Counter({ cell }: { cell: ReturnType<typeof createCell<number>> }) {
+  return createElement('span', { 'data-testid': 'v' }, String(useCell(cell)))
+}
+
+describe('useCell', () => {
+  it('renders the current value and re-renders when the cell changes', () => {
+    const cell = createCell('r.count', 1)
+    const view = render(createElement(Counter, { cell }))
+    expect(view.getByTestId('v').textContent).toBe('1')
+    act(() => { cell.set(2) })
+    expect(view.getByTestId('v').textContent).toBe('2')
+  })
+
+  it('unsubscribes on unmount, and a second component on the same cell stays in step', () => {
+    const cell = createCell('r.count', 0)
+    let live = 0
+    const watched = { ...cell, subscribe: (listener: Parameters<typeof cell.subscribe>[0]) => { live += 1; const stop = cell.subscribe(listener); return () => { live -= 1; stop() } } }
+    const a = render(createElement(Counter, { cell: watched }))
+    const b = render(createElement(Counter, { cell: watched }))
+    expect(live).toBe(2)
+    act(() => { cell.set(7) })
+    expect(a.container.querySelector('[data-testid=v]')?.textContent).toBe('7')
+    expect(b.container.querySelector('[data-testid=v]')?.textContent).toBe('7')
+    a.unmount()
+    expect(live).toBe(1)
+    b.unmount()
+    expect(live).toBe(0)
+  })
+})