acryl-development-canvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ACRYL.dev
+
+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/README.md

@@ -0,0 +1,58 @@
+# ACRYL Development Canvas
+
+`acryl-development-canvas` is a standalone Host and Client Cordis plugin for
+the ACRYL Development Canvas. It adds a workspace canvas to compatible Desktop
+profiles, with terminal-backed tiles, file tiles, browser tiles, and a Client
+contribution to the `desktop.main` slot.
+
+## Install
+
+```sh
+dsh plugin --profile desktop add acryl-development-canvas
+```
+
+The package declares both a DSH bundle patch and an `acryl-package` manifest,
+so it is discoverable through the ACRYL package catalog as well as normal DSH
+plugin installation.
+
+## What it owns
+
+- The Host owns loopback PTY routes and every PTY process it starts.
+- The Client owns its Desktop slot contribution, xterm clients, injected
+  styles, and browser-side cleanup.
+- Removing the Loader row unregisters routes, closes PTYs, removes the Canvas
+  contribution, and restores the default conversation surface.
+
+## Engineering principles
+
+- **Dependency inversion and separated interfaces.** The Host consumes the
+  normal `webServer` capability; the Client consumes `slots`. Neither imports a
+  concrete Desktop bootstrap or creates another plugin runtime.
+- **One owner for live resources.** Routes, PTYs, subscriptions, styles, and
+  slot registrations are acquired inside their owning Cordis effects and
+  disposed with their Fibers.
+- **Reversible composition.** The stable Loader row controls the capability.
+  Disable, unload, or replacement removes only Canvas contributions.
+- **Orthogonality and information hiding.** Host process control and Client
+  presentation remain separate; PTY transport does not become canonical agent
+  history or a global application service.
+- **Fail fast and contain failure.** A non-loopback Host is rejected before
+  routes mount, and partial route activation rolls back registrations.
+- **YAGNI.** The package uses the existing DSH/Cordis Host, Client, slot, and
+  Loader seams instead of creating another PTY registry, event bus, or
+  lifecycle system.
+- **Refactor-safe behavior.** Tests exercise activation, route rollback,
+  PTY disposal, Client cleanup, slot replacement, and repeated lifecycle use.
+
+## Package compatibility
+
+The Host requires a loopback DSH `webServer`. The Client is intended for a
+profile that declares the `desktop.main` slot. When that slot is absent, the
+Client leaves the profile untouched.
+
+## Provenance
+
+This package is a copy-only extraction from the ACRYL workspace. The source
+package remains in the main repository. See [`provenance.json`](./provenance.json)
+for the source boundary and [`docs/PLAN.md`](./docs/PLAN.md) for the Cordis
+lifecycle design.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: desktop-development-canvas
+      name: acryl-development-canvas

package/docs/PLAN.md

@@ -0,0 +1,40 @@
+# Development Canvas public package
+
+Date: 2026-09-09. Copy-only extraction of the existing ACRYL Development Canvas
+Host and Client Cordis plugin. The source package remains in the ACRYL monorepo.
+
+## Capability and plugin boundary
+
+The Canvas is independently configurable, mountable, and removable. The Host
+owns loopback PTY routes and live PTY processes. The Client owns its desktop
+slot contribution, browser-side PTY client, xterm resources, and styles.
+
+## Provides and consumes
+
+The Host hard-injects `webServer` and provides its owned routes. The Client
+hard-injects `slots`, contributes to `desktop.main` only while that declaration
+exists, and exposes no parallel service registry.
+
+## Effects and disposal
+
+One Host effect owns the route registrations and `CanvasPtyRegistry`; teardown
+removes routes in reverse order and awaits all PTY termination. The Client
+declaration effect owns the slot registration, styles, and client handles.
+
+## Configuration and composition
+
+The published `dsh.bundle.patch` inserts the stable
+`desktop-development-canvas` Loader row. The row is ordinary Cordis desired
+composition and supports disable/reload through the host Loader.
+
+## Events and durability
+
+PTY bytes and Canvas view state are presentation/transport concerns, not a
+canonical agent history. Durable agent/room facts remain owned by their runtime
+services. This package does not create a second event or persistence system.
+
+## Verification and release
+
+The copied suite covers Host activation, route rollback/removal, PTY lifecycle,
+Client slot replacement, and client cleanup. Tags run build, typecheck, test,
+npm provenance publish, and GitHub release creation.

package/lib/canvas-pty-contract.d.ts

@@ -0,0 +1,17 @@
+/** Allowlisted Development Canvas PTY commands and loopback routes. */
+export declare const CANVAS_PTY_COMMAND_IDS: readonly ["shell", "claude", "codex", "opencode", "gemini", "pi", "grok", "aider", "goose", "amp", "kimi", "cursor", "hermes", "qwen"];
+export type CanvasPtyCommandId = (typeof CANVAS_PTY_COMMAND_IDS)[number];
+export declare const CANVAS_PTY_PATH = "/api/development-canvas/pty";
+export declare const CANVAS_PTY_INPUT_PATH = "/api/development-canvas/pty/input";
+export declare const CANVAS_PTY_RESIZE_PATH = "/api/development-canvas/pty/resize";
+export declare const CANVAS_PTY_CLOSE_PATH = "/api/development-canvas/pty/close";
+/** @param value - unknown command id from JSON. */
+export declare function isCanvasPtyCommandId(value: unknown): value is CanvasPtyCommandId;
+export type CanvasPtyStatus = 'starting' | 'running' | 'exited' | 'error';
+export interface CanvasPtyView {
+    readonly id: string;
+    readonly status: CanvasPtyStatus;
+    readonly output: string;
+    readonly exitCode: number | null;
+    readonly error: string | null;
+}

package/lib/canvas-pty-route.d.ts

@@ -0,0 +1,19 @@
+/** Same-origin JSON handlers for Development Canvas PTY sessions. */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { CanvasPtyRegistry } from './canvas-pty.ts';
+/**
+ * POST start and GET snapshot for the Canvas PTY route.
+ */
+export declare function handleCanvasPtyRequest(req: IncomingMessage, res: ServerResponse, expectedOrigin: string, registry: CanvasPtyRegistry, reportError: (operation: string, cause: unknown) => void): Promise<void>;
+/** POST stdin to a live session. */
+export declare function handleCanvasPtyInputRequest(req: IncomingMessage, res: ServerResponse, expectedOrigin: string, registry: CanvasPtyRegistry, reportError: (operation: string, cause: unknown) => void): Promise<void>;
+/** POST terminal dimensions to a live session. */
+export declare function handleCanvasPtyResizeRequest(req: IncomingMessage, res: ServerResponse, expectedOrigin: string, registry: CanvasPtyRegistry, reportError: (operation: string, cause: unknown) => void): Promise<void>;
+/** POST idempotent close. */
+export declare function handleCanvasPtyCloseRequest(req: IncomingMessage, res: ServerResponse, expectedOrigin: string, registry: CanvasPtyRegistry, reportError: (operation: string, cause: unknown) => void): Promise<void>;
+export declare const canvasPtyRoutePaths: {
+    readonly pty: "/api/development-canvas/pty";
+    readonly input: "/api/development-canvas/pty/input";
+    readonly resize: "/api/development-canvas/pty/resize";
+    readonly close: "/api/development-canvas/pty/close";
+};

package/lib/canvas-pty.d.ts

@@ -0,0 +1,82 @@
+/** Host-owned Development Canvas PTY sessions. UI observes; this module owns lifetime. */
+import type { CanvasPtyCommandId, CanvasPtyView } from './canvas-pty-contract.ts';
+/**
+ * A Finder-launched macOS app gets a minimal PATH (`/usr/bin:/bin:…`), so a
+ * bare agent name such as `claude` fails to spawn even when it is installed.
+ * Resolve bare commands to an absolute executable by merging `env.PATH` with
+ * the user's login-shell PATH (cached per registry).
+ */
+export declare function canvasPtySpawnDirs(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): string[];
+/**
+ * Return an absolute executable path for `command`, or `undefined` when none of
+ * `dirs` contains an executable `command`. Absolute/relative paths pass through.
+ */
+export declare function resolveCanvasPtyCommand(command: string, dirs: readonly string[], platform: NodeJS.Platform): string | undefined;
+export interface CanvasPtyProcess {
+    onData(listener: (data: string) => void): {
+        dispose(): void;
+    };
+    onExit(listener: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): {
+        dispose(): void;
+    };
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+}
+/** PTY spawn injected so unit tests never launch a real process. */
+export type CanvasPtySpawn = (command: string, args: readonly string[], options: {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly name: string;
+    readonly cols: number;
+    readonly rows: number;
+}) => CanvasPtyProcess;
+export interface CanvasPtySpawnPlan {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface CanvasPtyRegistryOptions {
+    readonly spawn?: CanvasPtySpawn;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly createId?: () => string;
+}
+/**
+ * Resolve argv for one allowlisted canvas command.
+ * @param commandId - catalog id from the tab.
+ * @param platform - Host process.platform.
+ * @param env - environment used to pick SHELL / ComSpec.
+ */
+export declare function planCanvasPtyCommand(commandId: CanvasPtyCommandId, platform: NodeJS.Platform, env: NodeJS.ProcessEnv): CanvasPtySpawnPlan;
+/** Table of live native PTY sessions for one Development Canvas Host fiber. */
+export declare class CanvasPtyRegistry {
+    private readonly sessions;
+    private readonly spawnImpl;
+    private readonly env;
+    private readonly cwd;
+    private readonly platform;
+    private readonly createId;
+    private readonly spawnDirs;
+    constructor(options?: CanvasPtyRegistryOptions);
+    /**
+     * Start one allowlisted command inside a real terminal.
+     * @param commandId - catalog id from the Terminal/agent tab.
+     */
+    start(commandId: string): CanvasPtyView;
+    /** Write exact terminal input bytes. */
+    write(id: string, data: string): void;
+    /** Resize one live terminal. */
+    resize(id: string, cols: number, rows: number): void;
+    /** Snapshot one session for the renderer. */
+    read(id: string): CanvasPtyView;
+    /** Stop one session. Idempotent. */
+    close(id: string): Promise<void>;
+    /** Stop every session owned by this fiber. */
+    disposeAll(): Promise<void>;
+    private require;
+    private view;
+}