dsh-generative-ui 0.0.0 → 0.0.2

package/types/README.md

@@ -0,0 +1,34 @@
+# `$dsh/*` type declarations
+
+Two import maps, because the commands want different things:
+
+| File | For | Targets |
+| --- | --- | --- |
+| `importmap.json` | `genui check`, `genui lint` | the `.d.ts` beside it |
+| `standalone/importmap.json` | `genui build`, `genui dev` | generated JS stubs |
+
+`build` and `dev` produce a page with no dsh around it, so the capabilities genuinely cannot
+work there — the conversation, the model and the workspace all live in the harness. The stubs
+make such a card *build* anyway: each call warns to the console and returns an empty value of
+the right shape (`""`, `[]`, an empty async iterator), so a page that `await`s one keeps
+running instead of dying on `undefined`. Everything that does not touch the harness — layout,
+styling, local state — is real. Anything that does is inert.
+
+`standalone/` is generated by `scripts/gen-standalone.ts`, which enumerates the export names
+from `bind()` rather than a second hand-written list, so a capability added to the
+implementation cannot go missing from the stubs. It runs before `build` and `prepare`.
+
+The declarations are hand-written rather than emitted from `src/client/runtime/bindings.ts`:
+what a card should see is the capability surface, not how it reaches the host.
+
+`check.ts` keeps them honest — it asserts the declared surface and `bind()`'s return type are
+assignable **both ways**, so a declaration that is narrower than the implementation (hiding
+capability) fails just as a wider one does (promising what the runtime will not do). Verified
+it catches both an added method and a changed signature. Editing a `.d.ts` therefore means
+editing the transcription in `check.ts` too; that duplication is the point, since a check that
+derives from the thing it checks proves nothing.
+
+Pointing the map at the real `.ts` sources instead was measured and rejected: `paths` targets
+are compiled as part of the program, so the implementation's own diagnostics — a module it
+imports, an error in a file beside it — surface as errors on the model'"'"'s card, about code the
+model cannot see or fix.

package/types/ai.d.ts

@@ -0,0 +1,14 @@
+/** `$dsh/ai` — stream from the app's own model. See `types/chat.d.ts` on why these are hand-written. */
+declare module "$dsh/ai" {
+  /**
+   * One user turn plus an optional system prompt; there is no conversation here.
+   *
+   * Pass `signal` when the card can start a second call before the first finishes — regenerating
+   * per keystroke, or a Stop button. Aborting stops the generation itself, not just your reading
+   * of it. The abort surfaces as an `AbortError`, which is the one rejection that is not a
+   * failure: `if (error.name === "AbortError") return;` before showing anything.
+   */
+  export type StreamOptions = { prompt: string; system?: string; signal?: AbortSignal };
+  /** Yields text as it arrives, one piece per network chunk. Inherits the app's model and credentials. */
+  export function streamText(options: StreamOptions | string): AsyncIterable<string>;
+}

package/types/chat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `$dsh/chat` — drive the next conversation turn from inside a card.
+ *
+ * Hand-written rather than emitted: the implementation's types are shaped by how it reaches
+ * the host, and what a card should see is the surface, not the plumbing. `types/check.ts`
+ * asserts the two stay assignable, so drift fails the build rather than the model.
+ */
+declare module "$dsh/chat" {
+  /**
+   * Sends a prompt into the current session, exactly as the composer would — the text lands
+   * in the transcript as the user's own message.
+   */
+  export function sendMessage(text: string): void;
+}

package/types/check.ts

@@ -0,0 +1,39 @@
+/**
+ * Asserts the hand-written `$dsh/*` declarations still describe what `bind()` returns.
+ *
+ * They are hand-written on purpose — a card should see the capability surface, not how it
+ * reaches the host — but a surface nobody checks drifts, and the model would find out by
+ * getting a false error from `genui check`. This file is type-only: `bun run typecheck` fails
+ * if a signature moves without its declaration moving too.
+ *
+ * The declarations are IMPORTED, not transcribed. An earlier version restated them by hand and
+ * said so: "editing a `.d.ts` alone changes nothing — replacing `bash(command: string)` with
+ * `bash(command: number)` leaves `tsc` silent." That was true, and it made this file a check on
+ * a copy rather than on the thing — the same shape as `compiler.test.ts` testing a
+ * re-implementation of its own module. `types/` is on the tsconfig `include`, so the ambient
+ * `declare module` blocks resolve here directly.
+ */
+import type * as Ai from "$dsh/ai";
+import type * as Chat from "$dsh/chat";
+import type * as Exec from "$dsh/exec";
+import type * as Web from "$dsh/web";
+import type * as Fs from "$dsh/fs";
+import type { bind } from "../src/client/runtime/bindings.ts";
+
+type Bound = ReturnType<typeof bind>;
+
+type Declared = {
+  chat: { sendMessage: typeof Chat.sendMessage };
+  ai: { streamText: typeof Ai.streamText };
+  fs: { readFile: typeof Fs.readFile; readdir: typeof Fs.readdir; readBytes: typeof Fs.readBytes; writeFile: typeof Fs.writeFile };
+  exec: { bash: typeof Exec.bash };
+  web: { search: typeof Web.search };
+  state: { usePersistedState: <T>(key: string, initial: T | (() => T)) => [T, import("react").Dispatch<import("react").SetStateAction<T>>] };
+};
+
+// Both directions: a declaration narrower than the implementation hides capability, and one
+// wider promises what the runtime will not do. Either way the model is told something untrue.
+const _implementationSatisfiesDeclaration: Declared = null as unknown as Bound;
+const _declarationCoversImplementation: Bound = null as unknown as Declared;
+void _implementationSatisfiesDeclaration;
+void _declarationCoversImplementation;

package/types/exec.d.ts

@@ -0,0 +1,17 @@
+/** `$dsh/exec` — one command in the workspace, under the session's own sandbox mode. */
+declare module "$dsh/exec" {
+  /** What a command left behind. `truncated` means output was cut, not that it failed. */
+  export type ExecResult = { stdout: string; stderr: string; exitCode: number | null; truncated: { stdout: boolean; stderr: boolean }; timedOut: boolean };
+  /**
+   * Runs `command` and resolves with its output.
+   *
+   * A non-zero exit RESOLVES — check `exitCode` rather than catching. Only a failure to run
+   * at all rejects. Commands are killed after 15 seconds.
+   *
+   * Pass a `signal` when the card runs commands on a timer or per keystroke: aborting kills
+   * the command itself, not just the wait, so a slow run cannot pile up behind the next one.
+   * An aborted call REJECTS with an `AbortError` — the one rejection that is not a failure,
+   * so ignore it rather than showing it (`if (e.name === "AbortError") return`).
+   */
+  export function bash(command: string, options?: { signal?: AbortSignal }): Promise<ExecResult>;
+}

package/types/fs.d.ts

@@ -0,0 +1,17 @@
+/** `$dsh/fs` — the workspace, under the session's own access mode. See `types/chat.d.ts`. */
+declare module "$dsh/fs" {
+  /** The file's text. Rejects when it does not exist or the session may not read it. */
+  export function readFile(path: string): Promise<string>;
+  /** One directory entry. Treat `size` as optional — draw nothing rather than `0 B` when it is missing. */
+  export type DirEntry = { name: string; type?: "file" | "directory"; size?: number };
+  /** A directory's entries — enough to draw a tree without probing each name. */
+  export function readdir(path: string): Promise<DirEntry[]>;
+  /**
+   * The file's raw bytes — for audio, MIDI, images, anything not text.
+   *
+   * `readFile` decodes as UTF-8 and would corrupt them silently. Capped at 8MB.
+   */
+  export function readBytes(path: string): Promise<Uint8Array<ArrayBuffer>>;
+  /** Rejects with `FS_SANDBOX_DENIED` when the session is read-only. */
+  export function writeFile(path: string, content: string): Promise<void>;
+}

package/types/importmap.json

@@ -0,0 +1,10 @@
+{
+  "imports": {
+    "$dsh/chat": "./chat.d.ts",
+    "$dsh/ai": "./ai.d.ts",
+    "$dsh/fs": "./fs.d.ts",
+    "$dsh/exec": "./exec.d.ts",
+    "$dsh/state": "./state.d.ts",
+    "$dsh/web": "./web.d.ts"
+  }
+}

package/types/standalone/ai.js

@@ -0,0 +1,7 @@
+// Generated by scripts/gen-standalone.ts — do not edit.
+// Stands in for $dsh/ai outside dsh, where the harness these forward to does not exist.
+export function streamText(...args) {
+  console.warn("[$dsh/ai] streamText() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return (async function* () {})();
+}
+export default { streamText };

package/types/standalone/chat.js

@@ -0,0 +1,6 @@
+// Generated by scripts/gen-standalone.ts — do not edit.
+// Stands in for $dsh/chat outside dsh, where the harness these forward to does not exist.
+export function sendMessage(...args) {
+  console.warn("[$dsh/chat] sendMessage() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+}
+export default { sendMessage };

package/types/standalone/exec.js

@@ -0,0 +1,7 @@
+// Generated by scripts/gen-standalone.ts — do not edit.
+// Stands in for $dsh/exec outside dsh, where the harness these forward to does not exist.
+export async function bash(...args) {
+  console.warn("[$dsh/exec] bash() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return { stdout: "", stderr: "", exitCode: 0, truncated: { stdout: false, stderr: false }, timedOut: false };
+}
+export default { bash };

package/types/standalone/fs.js

@@ -0,0 +1,18 @@
+// Generated by scripts/gen-standalone.ts — do not edit.
+// Stands in for $dsh/fs outside dsh, where the harness these forward to does not exist.
+export async function readFile(...args) {
+  console.warn("[$dsh/fs] readFile() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return "";
+}
+export async function readdir(...args) {
+  console.warn("[$dsh/fs] readdir() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return [];
+}
+export async function readBytes(...args) {
+  console.warn("[$dsh/fs] readBytes() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return new Uint8Array();
+}
+export async function writeFile(...args) {
+  console.warn("[$dsh/fs] writeFile() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+}
+export default { readFile, readdir, readBytes, writeFile };

package/types/standalone/importmap.json

@@ -0,0 +1,10 @@
+{
+  "imports": {
+    "$dsh/chat": "./chat.js",
+    "$dsh/ai": "./ai.js",
+    "$dsh/fs": "./fs.js",
+    "$dsh/exec": "./exec.js",
+    "$dsh/web": "./web.js",
+    "$dsh/state": "./state.js"
+  }
+}

package/types/standalone/state.js

@@ -0,0 +1,24 @@
+// src/client/runtime/state.ts
+import * as React from "react";
+var scope = (key) => `dsh-genui:${key}`;
+function read(key, initial) {
+  const fallback = () => typeof initial === "function" ? initial() : initial;
+  try {
+    const raw = globalThis.localStorage?.getItem(scope(key));
+    return raw === null || raw === undefined ? fallback() : JSON.parse(raw);
+  } catch {
+    return fallback();
+  }
+}
+function usePersistedState(key, initial) {
+  const [value, setValue] = React.useState(() => read(key, initial));
+  React.useEffect(() => {
+    try {
+      globalThis.localStorage?.setItem(scope(key), JSON.stringify(value));
+    } catch {}
+  }, [key, value]);
+  return [value, setValue];
+}
+export {
+  usePersistedState
+};

package/types/standalone/web.js

@@ -0,0 +1,7 @@
+// Generated by scripts/gen-standalone.ts — do not edit.
+// Stands in for $dsh/web outside dsh, where the harness these forward to does not exist.
+export async function search(...args) {
+  console.warn("[$dsh/web] search() did nothing: this page is not running inside dsh, so there is no harness to reach.", ...args);
+  return { sources: [], truncated: false };
+}
+export default { search };

package/types/state.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `$dsh/state` — state that survives a remount.
+ *
+ * Hand-written rather than emitted, like the rest of `types/*.d.ts`; `types/check.ts` asserts it
+ * stays assignable to what `bind()` returns.
+ *
+ * This is the one capability with nothing behind it — no host call, no network. It exists because
+ * three independent runs of a habit-tracker prompt imported exactly this name from exactly this
+ * module without being told it was there, and an unresolvable specifier renders a blank card.
+ */
+declare module "$dsh/state" {
+  import type { Dispatch, SetStateAction } from "react";
+
+  /**
+   * `useState`, except the value is written to `localStorage` under a namespaced key and read
+   * back on mount.
+   *
+   * Reach for it whenever losing the value would be a bug: a canvas is remounted by every
+   * revision you make to it, and an inline card by any transcript re-render. Both are
+   * indistinguishable from a reload, and neither is rare.
+   *
+   * `initial` may be a value or a lazy initialiser, exactly as in `useState`.
+   */
+  export function usePersistedState<T>(key: string, initial: T | (() => T)): [T, Dispatch<SetStateAction<T>>];
+}

package/types/web.d.ts

@@ -0,0 +1,31 @@
+/** `$dsh/web` — one web search, through whichever provider the host composed. */
+declare module "$dsh/web" {
+  /** One citeable result. Only `url` is guaranteed: not every provider returns the rest. */
+  export type SearchSource = {
+    url: string;
+    title?: string;
+    snippet?: string;
+    /** Publication or crawl time, as the provider's own ISO-8601 string. */
+    publishedAt?: string;
+  };
+  /** What one search returns. */
+  export type SearchResult = {
+    /** A generated answer or summary, when the provider makes one — DeepSeek and Exa do not. */
+    content?: string;
+    sources: readonly SearchSource[];
+    /** True when the result set was cut down to `maxResults`. */
+    truncated: boolean;
+  };
+  /**
+   * Runs one search and resolves with its sources.
+   *
+   * **Search only — there is no `fetch` here.** A card cannot retrieve a page body; render the
+   * snippet and link to the source instead. Show the sources you used: a card that states a fact
+   * from the web without the link it came from cannot be checked, and this is the one capability
+   * whose output the reader has no other way to verify.
+   *
+   * Pass a `signal` when searching as the reader types. An aborted call REJECTS with an
+   * `AbortError`, which is not a failure — ignore it (`if (e.name === "AbortError") return`).
+   */
+  export function search(query: string, options?: { maxResults?: number; signal?: AbortSignal }): Promise<SearchResult>;
+}

package/index.js

@@ -1 +0,0 @@
-// Placeholder