@hyperfixi/speech 2.4.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025 LokaScript Contributors
+
+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,85 @@
+# @hyperfixi/speech
+
+Web Speech API + `prompt()` plugin for [hyperfixi](https://github.com/codetalcott/hyperfixi). Adds three commands from upstream `_hyperscript 0.9.90`:
+
+| Command                                   | Purpose                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `speak "<text>" [with <option> <value>]*` | Speaks the text via `window.speechSynthesis`. Optional rate/pitch/voice/volume.                   |
+| `ask "<prompt>" [with default "<value>"]` | Calls `window.prompt()` and writes the answer to `result` and `it`.                               |
+| `answer with "<value>"`                   | Sets `result` and `it` to the value without prompting — useful for scripted flows and test mocks. |
+
+## Install
+
+```ts
+import { createRuntime, installPlugin } from '@hyperfixi/core';
+import { speechPlugin } from '@hyperfixi/speech';
+
+const runtime = createRuntime();
+installPlugin(runtime, speechPlugin);
+```
+
+Re-installing is safe: the plugin registers idempotent command keywords with the parser and replaces the existing command implementations in the runtime registry with identical ones.
+
+## `speak`
+
+```hyperscript
+speak "Welcome back"
+speak "Hello" with rate 1.5 with pitch 0.8
+speak "Bonjour" with voice "Google français"
+speak "Loud and clear" with volume 1 with rate 1.2
+```
+
+Options (all optional, any combination, in any order):
+
+| Option   | Type   | Notes                                                                                                                  |
+| -------- | ------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `rate`   | number | Forwarded to `SpeechSynthesisUtterance.rate`. Browser default 1; valid range typically 0.1 – 10.                       |
+| `pitch`  | number | Forwarded to `SpeechSynthesisUtterance.pitch`. Browser default 1; valid range typically 0 – 2.                         |
+| `volume` | number | Forwarded to `SpeechSynthesisUtterance.volume`. Browser default 1; valid range 0 – 1.                                  |
+| `voice`  | string | Matched against `speechSynthesis.getVoices()` by `.name`. If no voice matches, the utterance uses the browser default. |
+
+Side effects: `context.result` is set to `true` on success, `false` when the Web Speech API is unavailable (Node, restricted contexts). The command never throws on missing browser support — it silently no-ops so the surrounding handler can keep running.
+
+## `ask`
+
+```hyperscript
+ask "What's your name?"
+put result into #greeting
+
+ask "Username?" with default "guest"
+```
+
+Calls `window.prompt(text, defaultValue?)`. The user's answer is written to **both** `context.result` and `context.it`, so the natural follow-up is `put it into ...` or `put result into ...`.
+
+When `window.prompt` isn't available (headless / Node), the command returns `null` without setting `result` — let callers detect "no UI" by checking the value before using it.
+
+## `answer`
+
+```hyperscript
+answer with "programmatic value"
+-- result and it are now "programmatic value"
+
+answer "bare form also works"
+-- the leading `with` is optional
+```
+
+`answer` is the scripted counterpart to `ask` — no UI, just sets `result` and `it` to the given value. Useful for:
+
+- Stubbing user input in tests (`answer with "Test User"` to drive a flow that normally reads from `ask`)
+- Forwarding a value through `result` without an intermediate `put` step
+
+## Notes on browser support
+
+- `speechSynthesis` is widely available but [voices load asynchronously on some browsers](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/getVoices). If `with voice "<name>"` doesn't apply, the named voice may not yet be in `getVoices()`; the utterance falls through to the browser default.
+- iOS Safari requires a user gesture (tap/click) before `speechSynthesis.speak()` will produce audio. Calling `speak` from a `DOMContentLoaded` handler will silently fail there — wire it to a button click instead.
+- `window.prompt()` is blocked by some browsers in cross-origin iframes; `ask` will return `null` in those contexts.
+
+## API exports
+
+- `speechPlugin` (default export): the `HyperfixiPlugin` to pass to `installPlugin`.
+- `speakCommand`, `askCommand`, `answerCommand`: the individual command implementations, exported for advanced wiring (e.g., registering against a custom registry).
+- Types: `SpeakCommandInput`, `AskCommandInput`, `AnswerCommandInput`.
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Speech plugin commands — upstream _hyperscript 0.9.90.
+ *
+ *   speak "text"                    SpeechSynthesis.speak(new Utterance(text))
+ *   speak "text" with rate 1.5      options on the utterance
+ *   speak "text" with pitch 0.8 with voice "Google UK English Female"
+ *
+ *   ask "Your name?"                window.prompt(text) → context.result
+ *   ask                             window.prompt()
+ *
+ *   answer with "programmatic"       context.result = text (no UI; useful for
+ *                                    scripted flows or test mocks)
+ *
+ * Each command returns a plain object with `{ name, parseInput, execute,
+ * validate }` — the minimum shape accepted by `CommandRegistryV2.register()`.
+ * The commands deliberately avoid importing from `@hyperfixi/core/commands`
+ * internals so the plugin stays a thin peer of the core package.
+ */
+interface ASTNode {
+    type: string;
+    name?: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+interface ExpressionEvaluator {
+    evaluate(node: ASTNode, context: unknown): Promise<unknown>;
+}
+interface ExecutionContext {
+    result?: unknown;
+    it?: unknown;
+    [k: string]: unknown;
+}
+interface RawCommandInput {
+    args: ASTNode[];
+    modifiers: Record<string, ASTNode>;
+}
+export interface SpeakCommandInput {
+    text: string;
+    rate?: number;
+    pitch?: number;
+    voice?: string;
+    volume?: number;
+}
+export declare const speakCommand: {
+    name: string;
+    parseInput(raw: RawCommandInput, evaluator: ExpressionEvaluator, context: ExecutionContext): Promise<SpeakCommandInput>;
+    execute(input: SpeakCommandInput, context: ExecutionContext): Promise<void>;
+    validate(input: unknown): boolean;
+};
+export interface AskCommandInput {
+    prompt?: string;
+    defaultValue?: string;
+}
+export declare const askCommand: {
+    name: string;
+    parseInput(raw: RawCommandInput, evaluator: ExpressionEvaluator, context: ExecutionContext): Promise<AskCommandInput>;
+    execute(input: AskCommandInput, context: ExecutionContext): Promise<unknown>;
+    validate(input: unknown): boolean;
+};
+export interface AnswerCommandInput {
+    value: unknown;
+}
+export declare const answerCommand: {
+    name: string;
+    parseInput(raw: RawCommandInput, evaluator: ExpressionEvaluator, context: ExecutionContext): Promise<AnswerCommandInput>;
+    execute(input: AnswerCommandInput, context: ExecutionContext): Promise<unknown>;
+    validate(input: unknown): boolean;
+};
+export {};

package/dist/index.cjs

@@ -0,0 +1,166 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  answerCommand: () => answerCommand,
+  askCommand: () => askCommand,
+  default: () => index_default,
+  speakCommand: () => speakCommand,
+  speechPlugin: () => speechPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/commands.ts
+async function parseSpeakOptions(args, startIndex, evaluator, context) {
+  const out = {};
+  let i = startIndex;
+  while (i < args.length) {
+    const tok = args[i];
+    if (tok?.type === "identifier" && tok.name?.toLowerCase() === "with") {
+      i++;
+      continue;
+    }
+    if (tok?.type === "identifier" && i + 1 < args.length) {
+      const key = tok.name.toLowerCase();
+      const value = await evaluator.evaluate(args[i + 1], context);
+      if (key === "rate" && typeof value === "number") out.rate = value;
+      else if (key === "pitch" && typeof value === "number") out.pitch = value;
+      else if (key === "volume" && typeof value === "number") out.volume = value;
+      else if (key === "voice" && typeof value === "string") out.voice = value;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return out;
+}
+var speakCommand = {
+  name: "speak",
+  async parseInput(raw, evaluator, context) {
+    if (!raw.args?.length) {
+      throw new Error("speak command requires a text argument");
+    }
+    const text = await evaluator.evaluate(raw.args[0], context);
+    const opts = await parseSpeakOptions(raw.args, 1, evaluator, context);
+    return { text: text == null ? "" : String(text), ...opts };
+  },
+  async execute(input, context) {
+    const synth = typeof globalThis !== "undefined" ? globalThis.speechSynthesis : void 0;
+    if (!synth || typeof SpeechSynthesisUtterance === "undefined") {
+      context.result = false;
+      return;
+    }
+    const utter = new SpeechSynthesisUtterance(input.text);
+    if (input.rate != null) utter.rate = input.rate;
+    if (input.pitch != null) utter.pitch = input.pitch;
+    if (input.volume != null) utter.volume = input.volume;
+    if (input.voice != null) {
+      const voices = synth.getVoices?.() ?? [];
+      const match = voices.find((v) => v.name === input.voice);
+      if (match) utter.voice = match;
+    }
+    synth.speak(utter);
+    context.result = true;
+  },
+  validate(input) {
+    return !!input && typeof input === "object" && typeof input.text === "string";
+  }
+};
+var askCommand = {
+  name: "ask",
+  async parseInput(raw, evaluator, context) {
+    const out = {};
+    if (raw.args?.length) {
+      const promptValue = await evaluator.evaluate(raw.args[0], context);
+      if (promptValue != null) out.prompt = String(promptValue);
+    }
+    for (let i = 1; i < (raw.args?.length ?? 0) - 1; i++) {
+      const tok = raw.args[i];
+      const next = raw.args[i + 1];
+      if (tok?.type === "identifier" && tok.name?.toLowerCase() === "default" && next) {
+        const defaultVal = await evaluator.evaluate(next, context);
+        if (defaultVal != null) out.defaultValue = String(defaultVal);
+      }
+    }
+    return out;
+  },
+  async execute(input, context) {
+    const win = typeof globalThis !== "undefined" ? globalThis : void 0;
+    if (!win || typeof win.prompt !== "function") {
+      return null;
+    }
+    const answer = win.prompt(input.prompt ?? "", input.defaultValue ?? "");
+    context.result = answer;
+    context.it = answer;
+    return answer;
+  },
+  validate(input) {
+    return typeof input === "object" && input !== null;
+  }
+};
+var answerCommand = {
+  name: "answer",
+  async parseInput(raw, evaluator, context) {
+    if (!raw.args?.length) {
+      throw new Error('answer command requires a value (e.g. `answer with "text"`)');
+    }
+    let valueIndex = 0;
+    const first = raw.args[0];
+    if (first?.type === "identifier" && first.name?.toLowerCase() === "with") {
+      valueIndex = 1;
+    }
+    if (valueIndex >= raw.args.length) {
+      throw new Error("answer command requires a value after `with`");
+    }
+    const value = await evaluator.evaluate(raw.args[valueIndex], context);
+    return { value };
+  },
+  async execute(input, context) {
+    context.result = input.value;
+    context.it = input.value;
+    return input.value;
+  },
+  validate(input) {
+    return typeof input === "object" && input !== null && "value" in input;
+  }
+};
+
+// src/index.ts
+var speechPlugin = {
+  name: "@hyperfixi/speech",
+  install({ commandRegistry, parserExtensions }) {
+    parserExtensions.registerCommand("speak");
+    parserExtensions.registerCommand("ask");
+    parserExtensions.registerCommand("answer");
+    commandRegistry.register(speakCommand);
+    commandRegistry.register(askCommand);
+    commandRegistry.register(answerCommand);
+  }
+};
+var index_default = speechPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  answerCommand,
+  askCommand,
+  speakCommand,
+  speechPlugin
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/commands.ts"],"sourcesContent":["/**\n * @hyperfixi/speech — Web Speech API + prompt() plugin for hyperfixi.\n *\n * Adds three commands from upstream _hyperscript 0.9.90:\n *\n *   speak \"text\" [with rate N] [with pitch N] [with voice \"Name\"]\n *   ask \"prompt\"                   → context.result = user's answer\n *   answer with \"text\"             → context.result = text (scripted)\n *\n * Installation:\n *\n * ```ts\n * import { createRuntime, installPlugin } from '@hyperfixi/core';\n * import { speechPlugin } from '@hyperfixi/speech';\n *\n * const runtime = createRuntime();\n * installPlugin(runtime, speechPlugin);\n * ```\n */\n\nimport type { HyperfixiPlugin, HyperfixiPluginContext } from '@hyperfixi/core';\nimport { speakCommand, askCommand, answerCommand } from './commands';\n\nexport { speakCommand, askCommand, answerCommand };\nexport type { SpeakCommandInput, AskCommandInput, AnswerCommandInput } from './commands';\n\n/**\n * Plugin object for one-shot installation. Registers three command keywords\n * with the parser and three command implementations with the runtime.\n *\n * Idempotent: re-installing in the same process is a no-op for the parser\n * (keywords are Set-based) and replaces the existing command implementations\n * with identical ones in the runtime registry.\n */\nexport const speechPlugin: HyperfixiPlugin = {\n  name: '@hyperfixi/speech',\n  install({ commandRegistry, parserExtensions }: HyperfixiPluginContext) {\n    parserExtensions.registerCommand('speak');\n    parserExtensions.registerCommand('ask');\n    parserExtensions.registerCommand('answer');\n    commandRegistry.register(speakCommand as never);\n    commandRegistry.register(askCommand as never);\n    commandRegistry.register(answerCommand as never);\n  },\n};\n\nexport default speechPlugin;\n","/**\n * Speech plugin commands — upstream _hyperscript 0.9.90.\n *\n *   speak \"text\"                    SpeechSynthesis.speak(new Utterance(text))\n *   speak \"text\" with rate 1.5      options on the utterance\n *   speak \"text\" with pitch 0.8 with voice \"Google UK English Female\"\n *\n *   ask \"Your name?\"                window.prompt(text) → context.result\n *   ask                             window.prompt()\n *\n *   answer with \"programmatic\"       context.result = text (no UI; useful for\n *                                    scripted flows or test mocks)\n *\n * Each command returns a plain object with `{ name, parseInput, execute,\n * validate }` — the minimum shape accepted by `CommandRegistryV2.register()`.\n * The commands deliberately avoid importing from `@hyperfixi/core/commands`\n * internals so the plugin stays a thin peer of the core package.\n */\n\n// Lightweight type stubs — the plugin consumes raw shapes rather than import\n// tightly from core internals, keeping the package self-contained.\ninterface ASTNode {\n  type: string;\n  name?: string;\n  value?: unknown;\n  [k: string]: unknown;\n}\ninterface ExpressionEvaluator {\n  evaluate(node: ASTNode, context: unknown): Promise<unknown>;\n}\ninterface ExecutionContext {\n  result?: unknown;\n  it?: unknown;\n  [k: string]: unknown;\n}\n\ninterface RawCommandInput {\n  args: ASTNode[];\n  modifiers: Record<string, ASTNode>;\n}\n\n// ---------------------------------------------------------------------------\n// speak\n// ---------------------------------------------------------------------------\n\nexport interface SpeakCommandInput {\n  text: string;\n  rate?: number;\n  pitch?: number;\n  voice?: string;\n  volume?: number;\n}\n\n/**\n * Consume a leading `with` identifier followed by option pairs like\n * `rate 1.5`, `pitch 0.8`, `voice \"Google UK English Female\"`. Accepts\n * multiple `with <key> <value>` pairs.\n */\nasync function parseSpeakOptions(\n  args: ASTNode[],\n  startIndex: number,\n  evaluator: ExpressionEvaluator,\n  context: unknown\n): Promise<Omit<SpeakCommandInput, 'text'>> {\n  const out: Omit<SpeakCommandInput, 'text'> = {};\n  let i = startIndex;\n  while (i < args.length) {\n    const tok = args[i];\n    if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'with') {\n      i++;\n      continue;\n    }\n    if (tok?.type === 'identifier' && i + 1 < args.length) {\n      const key = (tok.name as string).toLowerCase();\n      const value = await evaluator.evaluate(args[i + 1], context);\n      if (key === 'rate' && typeof value === 'number') out.rate = value;\n      else if (key === 'pitch' && typeof value === 'number') out.pitch = value;\n      else if (key === 'volume' && typeof value === 'number') out.volume = value;\n      else if (key === 'voice' && typeof value === 'string') out.voice = value;\n      i += 2;\n      continue;\n    }\n    i++;\n  }\n  return out;\n}\n\nexport const speakCommand = {\n  name: 'speak',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<SpeakCommandInput> {\n    if (!raw.args?.length) {\n      throw new Error('speak command requires a text argument');\n    }\n    const text = await evaluator.evaluate(raw.args[0], context);\n    const opts = await parseSpeakOptions(raw.args, 1, evaluator, context);\n    return { text: text == null ? '' : String(text), ...opts };\n  },\n  async execute(input: SpeakCommandInput, context: ExecutionContext): Promise<void> {\n    const synth =\n      typeof globalThis !== 'undefined'\n        ? (globalThis as unknown as { speechSynthesis?: SpeechSynthesis }).speechSynthesis\n        : undefined;\n    if (!synth || typeof SpeechSynthesisUtterance === 'undefined') {\n      // No Web Speech API available — no-op. Downstream consumers can detect\n      // this by observing that `context.result` is still set (see below).\n      context.result = false;\n      return;\n    }\n    const utter = new SpeechSynthesisUtterance(input.text);\n    if (input.rate != null) utter.rate = input.rate;\n    if (input.pitch != null) utter.pitch = input.pitch;\n    if (input.volume != null) utter.volume = input.volume;\n    if (input.voice != null) {\n      const voices = synth.getVoices?.() ?? [];\n      const match = voices.find(v => v.name === input.voice);\n      if (match) utter.voice = match;\n    }\n    synth.speak(utter);\n    context.result = true;\n  },\n  validate(input: unknown): boolean {\n    return !!input && typeof input === 'object' && typeof (input as any).text === 'string';\n  },\n};\n\n// ---------------------------------------------------------------------------\n// ask\n// ---------------------------------------------------------------------------\n\nexport interface AskCommandInput {\n  prompt?: string;\n  defaultValue?: string;\n}\n\nexport const askCommand = {\n  name: 'ask',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<AskCommandInput> {\n    const out: AskCommandInput = {};\n    if (raw.args?.length) {\n      const promptValue = await evaluator.evaluate(raw.args[0], context);\n      if (promptValue != null) out.prompt = String(promptValue);\n    }\n    // Optional `with default \"X\"` form\n    for (let i = 1; i < (raw.args?.length ?? 0) - 1; i++) {\n      const tok = raw.args[i];\n      const next = raw.args[i + 1];\n      if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'default' && next) {\n        const defaultVal = await evaluator.evaluate(next, context);\n        if (defaultVal != null) out.defaultValue = String(defaultVal);\n      }\n    }\n    return out;\n  },\n  async execute(input: AskCommandInput, context: ExecutionContext): Promise<unknown> {\n    const win =\n      typeof globalThis !== 'undefined'\n        ? (globalThis as unknown as { prompt?: (p?: string, d?: string) => string | null })\n        : undefined;\n    if (!win || typeof win.prompt !== 'function') {\n      // No prompt available (e.g. Node headless) — no-op; leave result unset.\n      return null;\n    }\n    const answer = win.prompt(input.prompt ?? '', input.defaultValue ?? '');\n    context.result = answer;\n    context.it = answer;\n    return answer;\n  },\n  validate(input: unknown): boolean {\n    return typeof input === 'object' && input !== null;\n  },\n};\n\n// ---------------------------------------------------------------------------\n// answer\n// ---------------------------------------------------------------------------\n\nexport interface AnswerCommandInput {\n  value: unknown;\n}\n\nexport const answerCommand = {\n  name: 'answer',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<AnswerCommandInput> {\n    if (!raw.args?.length) {\n      throw new Error('answer command requires a value (e.g. `answer with \"text\"`)');\n    }\n    // Skip a leading `with` keyword if present: `answer with \"text\"`.\n    let valueIndex = 0;\n    const first = raw.args[0];\n    if (first?.type === 'identifier' && (first.name as string)?.toLowerCase() === 'with') {\n      valueIndex = 1;\n    }\n    if (valueIndex >= raw.args.length) {\n      throw new Error('answer command requires a value after `with`');\n    }\n    const value = await evaluator.evaluate(raw.args[valueIndex], context);\n    return { value };\n  },\n  async execute(input: AnswerCommandInput, context: ExecutionContext): Promise<unknown> {\n    context.result = input.value;\n    context.it = input.value;\n    return input.value;\n  },\n  validate(input: unknown): boolean {\n    return typeof input === 'object' && input !== null && 'value' in (input as object);\n  },\n};\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @hyperfixi/speech — Web Speech API + prompt() plugin for hyperfixi.
+ *
+ * Adds three commands from upstream _hyperscript 0.9.90:
+ *
+ *   speak "text" [with rate N] [with pitch N] [with voice "Name"]
+ *   ask "prompt"                   → context.result = user's answer
+ *   answer with "text"             → context.result = text (scripted)
+ *
+ * Installation:
+ *
+ * ```ts
+ * import { createRuntime, installPlugin } from '@hyperfixi/core';
+ * import { speechPlugin } from '@hyperfixi/speech';
+ *
+ * const runtime = createRuntime();
+ * installPlugin(runtime, speechPlugin);
+ * ```
+ */
+import type { HyperfixiPlugin } from '@hyperfixi/core';
+import { speakCommand, askCommand, answerCommand } from './commands';
+export { speakCommand, askCommand, answerCommand };
+export type { SpeakCommandInput, AskCommandInput, AnswerCommandInput } from './commands';
+/**
+ * Plugin object for one-shot installation. Registers three command keywords
+ * with the parser and three command implementations with the runtime.
+ *
+ * Idempotent: re-installing in the same process is a no-op for the parser
+ * (keywords are Set-based) and replaces the existing command implementations
+ * with identical ones in the runtime registry.
+ */
+export declare const speechPlugin: HyperfixiPlugin;
+export default speechPlugin;

package/dist/index.js

@@ -0,0 +1,136 @@
+// src/commands.ts
+async function parseSpeakOptions(args, startIndex, evaluator, context) {
+  const out = {};
+  let i = startIndex;
+  while (i < args.length) {
+    const tok = args[i];
+    if (tok?.type === "identifier" && tok.name?.toLowerCase() === "with") {
+      i++;
+      continue;
+    }
+    if (tok?.type === "identifier" && i + 1 < args.length) {
+      const key = tok.name.toLowerCase();
+      const value = await evaluator.evaluate(args[i + 1], context);
+      if (key === "rate" && typeof value === "number") out.rate = value;
+      else if (key === "pitch" && typeof value === "number") out.pitch = value;
+      else if (key === "volume" && typeof value === "number") out.volume = value;
+      else if (key === "voice" && typeof value === "string") out.voice = value;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return out;
+}
+var speakCommand = {
+  name: "speak",
+  async parseInput(raw, evaluator, context) {
+    if (!raw.args?.length) {
+      throw new Error("speak command requires a text argument");
+    }
+    const text = await evaluator.evaluate(raw.args[0], context);
+    const opts = await parseSpeakOptions(raw.args, 1, evaluator, context);
+    return { text: text == null ? "" : String(text), ...opts };
+  },
+  async execute(input, context) {
+    const synth = typeof globalThis !== "undefined" ? globalThis.speechSynthesis : void 0;
+    if (!synth || typeof SpeechSynthesisUtterance === "undefined") {
+      context.result = false;
+      return;
+    }
+    const utter = new SpeechSynthesisUtterance(input.text);
+    if (input.rate != null) utter.rate = input.rate;
+    if (input.pitch != null) utter.pitch = input.pitch;
+    if (input.volume != null) utter.volume = input.volume;
+    if (input.voice != null) {
+      const voices = synth.getVoices?.() ?? [];
+      const match = voices.find((v) => v.name === input.voice);
+      if (match) utter.voice = match;
+    }
+    synth.speak(utter);
+    context.result = true;
+  },
+  validate(input) {
+    return !!input && typeof input === "object" && typeof input.text === "string";
+  }
+};
+var askCommand = {
+  name: "ask",
+  async parseInput(raw, evaluator, context) {
+    const out = {};
+    if (raw.args?.length) {
+      const promptValue = await evaluator.evaluate(raw.args[0], context);
+      if (promptValue != null) out.prompt = String(promptValue);
+    }
+    for (let i = 1; i < (raw.args?.length ?? 0) - 1; i++) {
+      const tok = raw.args[i];
+      const next = raw.args[i + 1];
+      if (tok?.type === "identifier" && tok.name?.toLowerCase() === "default" && next) {
+        const defaultVal = await evaluator.evaluate(next, context);
+        if (defaultVal != null) out.defaultValue = String(defaultVal);
+      }
+    }
+    return out;
+  },
+  async execute(input, context) {
+    const win = typeof globalThis !== "undefined" ? globalThis : void 0;
+    if (!win || typeof win.prompt !== "function") {
+      return null;
+    }
+    const answer = win.prompt(input.prompt ?? "", input.defaultValue ?? "");
+    context.result = answer;
+    context.it = answer;
+    return answer;
+  },
+  validate(input) {
+    return typeof input === "object" && input !== null;
+  }
+};
+var answerCommand = {
+  name: "answer",
+  async parseInput(raw, evaluator, context) {
+    if (!raw.args?.length) {
+      throw new Error('answer command requires a value (e.g. `answer with "text"`)');
+    }
+    let valueIndex = 0;
+    const first = raw.args[0];
+    if (first?.type === "identifier" && first.name?.toLowerCase() === "with") {
+      valueIndex = 1;
+    }
+    if (valueIndex >= raw.args.length) {
+      throw new Error("answer command requires a value after `with`");
+    }
+    const value = await evaluator.evaluate(raw.args[valueIndex], context);
+    return { value };
+  },
+  async execute(input, context) {
+    context.result = input.value;
+    context.it = input.value;
+    return input.value;
+  },
+  validate(input) {
+    return typeof input === "object" && input !== null && "value" in input;
+  }
+};
+
+// src/index.ts
+var speechPlugin = {
+  name: "@hyperfixi/speech",
+  install({ commandRegistry, parserExtensions }) {
+    parserExtensions.registerCommand("speak");
+    parserExtensions.registerCommand("ask");
+    parserExtensions.registerCommand("answer");
+    commandRegistry.register(speakCommand);
+    commandRegistry.register(askCommand);
+    commandRegistry.register(answerCommand);
+  }
+};
+var index_default = speechPlugin;
+export {
+  answerCommand,
+  askCommand,
+  index_default as default,
+  speakCommand,
+  speechPlugin
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands.ts","../src/index.ts"],"sourcesContent":["/**\n * Speech plugin commands — upstream _hyperscript 0.9.90.\n *\n *   speak \"text\"                    SpeechSynthesis.speak(new Utterance(text))\n *   speak \"text\" with rate 1.5      options on the utterance\n *   speak \"text\" with pitch 0.8 with voice \"Google UK English Female\"\n *\n *   ask \"Your name?\"                window.prompt(text) → context.result\n *   ask                             window.prompt()\n *\n *   answer with \"programmatic\"       context.result = text (no UI; useful for\n *                                    scripted flows or test mocks)\n *\n * Each command returns a plain object with `{ name, parseInput, execute,\n * validate }` — the minimum shape accepted by `CommandRegistryV2.register()`.\n * The commands deliberately avoid importing from `@hyperfixi/core/commands`\n * internals so the plugin stays a thin peer of the core package.\n */\n\n// Lightweight type stubs — the plugin consumes raw shapes rather than import\n// tightly from core internals, keeping the package self-contained.\ninterface ASTNode {\n  type: string;\n  name?: string;\n  value?: unknown;\n  [k: string]: unknown;\n}\ninterface ExpressionEvaluator {\n  evaluate(node: ASTNode, context: unknown): Promise<unknown>;\n}\ninterface ExecutionContext {\n  result?: unknown;\n  it?: unknown;\n  [k: string]: unknown;\n}\n\ninterface RawCommandInput {\n  args: ASTNode[];\n  modifiers: Record<string, ASTNode>;\n}\n\n// ---------------------------------------------------------------------------\n// speak\n// ---------------------------------------------------------------------------\n\nexport interface SpeakCommandInput {\n  text: string;\n  rate?: number;\n  pitch?: number;\n  voice?: string;\n  volume?: number;\n}\n\n/**\n * Consume a leading `with` identifier followed by option pairs like\n * `rate 1.5`, `pitch 0.8`, `voice \"Google UK English Female\"`. Accepts\n * multiple `with <key> <value>` pairs.\n */\nasync function parseSpeakOptions(\n  args: ASTNode[],\n  startIndex: number,\n  evaluator: ExpressionEvaluator,\n  context: unknown\n): Promise<Omit<SpeakCommandInput, 'text'>> {\n  const out: Omit<SpeakCommandInput, 'text'> = {};\n  let i = startIndex;\n  while (i < args.length) {\n    const tok = args[i];\n    if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'with') {\n      i++;\n      continue;\n    }\n    if (tok?.type === 'identifier' && i + 1 < args.length) {\n      const key = (tok.name as string).toLowerCase();\n      const value = await evaluator.evaluate(args[i + 1], context);\n      if (key === 'rate' && typeof value === 'number') out.rate = value;\n      else if (key === 'pitch' && typeof value === 'number') out.pitch = value;\n      else if (key === 'volume' && typeof value === 'number') out.volume = value;\n      else if (key === 'voice' && typeof value === 'string') out.voice = value;\n      i += 2;\n      continue;\n    }\n    i++;\n  }\n  return out;\n}\n\nexport const speakCommand = {\n  name: 'speak',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<SpeakCommandInput> {\n    if (!raw.args?.length) {\n      throw new Error('speak command requires a text argument');\n    }\n    const text = await evaluator.evaluate(raw.args[0], context);\n    const opts = await parseSpeakOptions(raw.args, 1, evaluator, context);\n    return { text: text == null ? '' : String(text), ...opts };\n  },\n  async execute(input: SpeakCommandInput, context: ExecutionContext): Promise<void> {\n    const synth =\n      typeof globalThis !== 'undefined'\n        ? (globalThis as unknown as { speechSynthesis?: SpeechSynthesis }).speechSynthesis\n        : undefined;\n    if (!synth || typeof SpeechSynthesisUtterance === 'undefined') {\n      // No Web Speech API available — no-op. Downstream consumers can detect\n      // this by observing that `context.result` is still set (see below).\n      context.result = false;\n      return;\n    }\n    const utter = new SpeechSynthesisUtterance(input.text);\n    if (input.rate != null) utter.rate = input.rate;\n    if (input.pitch != null) utter.pitch = input.pitch;\n    if (input.volume != null) utter.volume = input.volume;\n    if (input.voice != null) {\n      const voices = synth.getVoices?.() ?? [];\n      const match = voices.find(v => v.name === input.voice);\n      if (match) utter.voice = match;\n    }\n    synth.speak(utter);\n    context.result = true;\n  },\n  validate(input: unknown): boolean {\n    return !!input && typeof input === 'object' && typeof (input as any).text === 'string';\n  },\n};\n\n// ---------------------------------------------------------------------------\n// ask\n// ---------------------------------------------------------------------------\n\nexport interface AskCommandInput {\n  prompt?: string;\n  defaultValue?: string;\n}\n\nexport const askCommand = {\n  name: 'ask',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<AskCommandInput> {\n    const out: AskCommandInput = {};\n    if (raw.args?.length) {\n      const promptValue = await evaluator.evaluate(raw.args[0], context);\n      if (promptValue != null) out.prompt = String(promptValue);\n    }\n    // Optional `with default \"X\"` form\n    for (let i = 1; i < (raw.args?.length ?? 0) - 1; i++) {\n      const tok = raw.args[i];\n      const next = raw.args[i + 1];\n      if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'default' && next) {\n        const defaultVal = await evaluator.evaluate(next, context);\n        if (defaultVal != null) out.defaultValue = String(defaultVal);\n      }\n    }\n    return out;\n  },\n  async execute(input: AskCommandInput, context: ExecutionContext): Promise<unknown> {\n    const win =\n      typeof globalThis !== 'undefined'\n        ? (globalThis as unknown as { prompt?: (p?: string, d?: string) => string | null })\n        : undefined;\n    if (!win || typeof win.prompt !== 'function') {\n      // No prompt available (e.g. Node headless) — no-op; leave result unset.\n      return null;\n    }\n    const answer = win.prompt(input.prompt ?? '', input.defaultValue ?? '');\n    context.result = answer;\n    context.it = answer;\n    return answer;\n  },\n  validate(input: unknown): boolean {\n    return typeof input === 'object' && input !== null;\n  },\n};\n\n// ---------------------------------------------------------------------------\n// answer\n// ---------------------------------------------------------------------------\n\nexport interface AnswerCommandInput {\n  value: unknown;\n}\n\nexport const answerCommand = {\n  name: 'answer',\n  async parseInput(\n    raw: RawCommandInput,\n    evaluator: ExpressionEvaluator,\n    context: ExecutionContext\n  ): Promise<AnswerCommandInput> {\n    if (!raw.args?.length) {\n      throw new Error('answer command requires a value (e.g. `answer with \"text\"`)');\n    }\n    // Skip a leading `with` keyword if present: `answer with \"text\"`.\n    let valueIndex = 0;\n    const first = raw.args[0];\n    if (first?.type === 'identifier' && (first.name as string)?.toLowerCase() === 'with') {\n      valueIndex = 1;\n    }\n    if (valueIndex >= raw.args.length) {\n      throw new Error('answer command requires a value after `with`');\n    }\n    const value = await evaluator.evaluate(raw.args[valueIndex], context);\n    return { value };\n  },\n  async execute(input: AnswerCommandInput, context: ExecutionContext): Promise<unknown> {\n    context.result = input.value;\n    context.it = input.value;\n    return input.value;\n  },\n  validate(input: unknown): boolean {\n    return typeof input === 'object' && input !== null && 'value' in (input as object);\n  },\n};\n","/**\n * @hyperfixi/speech — Web Speech API + prompt() plugin for hyperfixi.\n *\n * Adds three commands from upstream _hyperscript 0.9.90:\n *\n *   speak \"text\" [with rate N] [with pitch N] [with voice \"Name\"]\n *   ask \"prompt\"                   → context.result = user's answer\n *   answer with \"text\"             → context.result = text (scripted)\n *\n * Installation:\n *\n * ```ts\n * import { createRuntime, installPlugin } from '@hyperfixi/core';\n * import { speechPlugin } from '@hyperfixi/speech';\n *\n * const runtime = createRuntime();\n * installPlugin(runtime, speechPlugin);\n * ```\n */\n\nimport type { HyperfixiPlugin, HyperfixiPluginContext } from '@hyperfixi/core';\nimport { speakCommand, askCommand, answerCommand } from './commands';\n\nexport { speakCommand, askCommand, answerCommand };\nexport type { SpeakCommandInput, AskCommandInput, AnswerCommandInput } from './commands';\n\n/**\n * Plugin object for one-shot installation. Registers three command keywords\n * with the parser and three command implementations with the runtime.\n *\n * Idempotent: re-installing in the same process is a no-op for the parser\n * (keywords are Set-based) and replaces the existing command implementations\n * with identical ones in the runtime registry.\n */\nexport const speechPlugin: HyperfixiPlugin = {\n  name: '@hyperfixi/speech',\n  install({ commandRegistry, parserExtensions }: HyperfixiPluginContext) {\n    parserExtensions.registerCommand('speak');\n    parserExtensions.registerCommand('ask');\n    parserExtensions.registerCommand('answer');\n    commandRegistry.register(speakCommand as never);\n    commandRegistry.register(askCommand as never);\n    commandRegistry.register(answerCommand as never);\n  },\n};\n\nexport default speechPlugin;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@hyperfixi/speech",
+  "version": "2.4.0",
+  "description": "Speech Synthesis and prompt() plugin for hyperfixi — adds `speak`, `ask`, and `answer` commands (upstream _hyperscript 0.9.90).",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup && npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist --noEmit false",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:check": "vitest run --reporter=dot 2>&1 | tail -5",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hyperfixi/core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "happy-dom": "^20.9.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.5"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "hyperfixi",
+    "hyperscript",
+    "speech-synthesis",
+    "prompt",
+    "plugin",
+    "_hyperscript",
+    "v0.9.90"
+  ],
+  "author": "LokaScript Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codetalcott/hyperfixi.git",
+    "directory": "packages/speech"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,219 @@
+/**
+ * Speech plugin commands — upstream _hyperscript 0.9.90.
+ *
+ *   speak "text"                    SpeechSynthesis.speak(new Utterance(text))
+ *   speak "text" with rate 1.5      options on the utterance
+ *   speak "text" with pitch 0.8 with voice "Google UK English Female"
+ *
+ *   ask "Your name?"                window.prompt(text) → context.result
+ *   ask                             window.prompt()
+ *
+ *   answer with "programmatic"       context.result = text (no UI; useful for
+ *                                    scripted flows or test mocks)
+ *
+ * Each command returns a plain object with `{ name, parseInput, execute,
+ * validate }` — the minimum shape accepted by `CommandRegistryV2.register()`.
+ * The commands deliberately avoid importing from `@hyperfixi/core/commands`
+ * internals so the plugin stays a thin peer of the core package.
+ */
+
+// Lightweight type stubs — the plugin consumes raw shapes rather than import
+// tightly from core internals, keeping the package self-contained.
+interface ASTNode {
+  type: string;
+  name?: string;
+  value?: unknown;
+  [k: string]: unknown;
+}
+interface ExpressionEvaluator {
+  evaluate(node: ASTNode, context: unknown): Promise<unknown>;
+}
+interface ExecutionContext {
+  result?: unknown;
+  it?: unknown;
+  [k: string]: unknown;
+}
+
+interface RawCommandInput {
+  args: ASTNode[];
+  modifiers: Record<string, ASTNode>;
+}
+
+// ---------------------------------------------------------------------------
+// speak
+// ---------------------------------------------------------------------------
+
+export interface SpeakCommandInput {
+  text: string;
+  rate?: number;
+  pitch?: number;
+  voice?: string;
+  volume?: number;
+}
+
+/**
+ * Consume a leading `with` identifier followed by option pairs like
+ * `rate 1.5`, `pitch 0.8`, `voice "Google UK English Female"`. Accepts
+ * multiple `with <key> <value>` pairs.
+ */
+async function parseSpeakOptions(
+  args: ASTNode[],
+  startIndex: number,
+  evaluator: ExpressionEvaluator,
+  context: unknown
+): Promise<Omit<SpeakCommandInput, 'text'>> {
+  const out: Omit<SpeakCommandInput, 'text'> = {};
+  let i = startIndex;
+  while (i < args.length) {
+    const tok = args[i];
+    if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'with') {
+      i++;
+      continue;
+    }
+    if (tok?.type === 'identifier' && i + 1 < args.length) {
+      const key = (tok.name as string).toLowerCase();
+      const value = await evaluator.evaluate(args[i + 1], context);
+      if (key === 'rate' && typeof value === 'number') out.rate = value;
+      else if (key === 'pitch' && typeof value === 'number') out.pitch = value;
+      else if (key === 'volume' && typeof value === 'number') out.volume = value;
+      else if (key === 'voice' && typeof value === 'string') out.voice = value;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return out;
+}
+
+export const speakCommand = {
+  name: 'speak',
+  async parseInput(
+    raw: RawCommandInput,
+    evaluator: ExpressionEvaluator,
+    context: ExecutionContext
+  ): Promise<SpeakCommandInput> {
+    if (!raw.args?.length) {
+      throw new Error('speak command requires a text argument');
+    }
+    const text = await evaluator.evaluate(raw.args[0], context);
+    const opts = await parseSpeakOptions(raw.args, 1, evaluator, context);
+    return { text: text == null ? '' : String(text), ...opts };
+  },
+  async execute(input: SpeakCommandInput, context: ExecutionContext): Promise<void> {
+    const synth =
+      typeof globalThis !== 'undefined'
+        ? (globalThis as unknown as { speechSynthesis?: SpeechSynthesis }).speechSynthesis
+        : undefined;
+    if (!synth || typeof SpeechSynthesisUtterance === 'undefined') {
+      // No Web Speech API available — no-op. Downstream consumers can detect
+      // this by observing that `context.result` is still set (see below).
+      context.result = false;
+      return;
+    }
+    const utter = new SpeechSynthesisUtterance(input.text);
+    if (input.rate != null) utter.rate = input.rate;
+    if (input.pitch != null) utter.pitch = input.pitch;
+    if (input.volume != null) utter.volume = input.volume;
+    if (input.voice != null) {
+      const voices = synth.getVoices?.() ?? [];
+      const match = voices.find(v => v.name === input.voice);
+      if (match) utter.voice = match;
+    }
+    synth.speak(utter);
+    context.result = true;
+  },
+  validate(input: unknown): boolean {
+    return !!input && typeof input === 'object' && typeof (input as any).text === 'string';
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ask
+// ---------------------------------------------------------------------------
+
+export interface AskCommandInput {
+  prompt?: string;
+  defaultValue?: string;
+}
+
+export const askCommand = {
+  name: 'ask',
+  async parseInput(
+    raw: RawCommandInput,
+    evaluator: ExpressionEvaluator,
+    context: ExecutionContext
+  ): Promise<AskCommandInput> {
+    const out: AskCommandInput = {};
+    if (raw.args?.length) {
+      const promptValue = await evaluator.evaluate(raw.args[0], context);
+      if (promptValue != null) out.prompt = String(promptValue);
+    }
+    // Optional `with default "X"` form
+    for (let i = 1; i < (raw.args?.length ?? 0) - 1; i++) {
+      const tok = raw.args[i];
+      const next = raw.args[i + 1];
+      if (tok?.type === 'identifier' && (tok.name as string)?.toLowerCase() === 'default' && next) {
+        const defaultVal = await evaluator.evaluate(next, context);
+        if (defaultVal != null) out.defaultValue = String(defaultVal);
+      }
+    }
+    return out;
+  },
+  async execute(input: AskCommandInput, context: ExecutionContext): Promise<unknown> {
+    const win =
+      typeof globalThis !== 'undefined'
+        ? (globalThis as unknown as { prompt?: (p?: string, d?: string) => string | null })
+        : undefined;
+    if (!win || typeof win.prompt !== 'function') {
+      // No prompt available (e.g. Node headless) — no-op; leave result unset.
+      return null;
+    }
+    const answer = win.prompt(input.prompt ?? '', input.defaultValue ?? '');
+    context.result = answer;
+    context.it = answer;
+    return answer;
+  },
+  validate(input: unknown): boolean {
+    return typeof input === 'object' && input !== null;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// answer
+// ---------------------------------------------------------------------------
+
+export interface AnswerCommandInput {
+  value: unknown;
+}
+
+export const answerCommand = {
+  name: 'answer',
+  async parseInput(
+    raw: RawCommandInput,
+    evaluator: ExpressionEvaluator,
+    context: ExecutionContext
+  ): Promise<AnswerCommandInput> {
+    if (!raw.args?.length) {
+      throw new Error('answer command requires a value (e.g. `answer with "text"`)');
+    }
+    // Skip a leading `with` keyword if present: `answer with "text"`.
+    let valueIndex = 0;
+    const first = raw.args[0];
+    if (first?.type === 'identifier' && (first.name as string)?.toLowerCase() === 'with') {
+      valueIndex = 1;
+    }
+    if (valueIndex >= raw.args.length) {
+      throw new Error('answer command requires a value after `with`');
+    }
+    const value = await evaluator.evaluate(raw.args[valueIndex], context);
+    return { value };
+  },
+  async execute(input: AnswerCommandInput, context: ExecutionContext): Promise<unknown> {
+    context.result = input.value;
+    context.it = input.value;
+    return input.value;
+  },
+  validate(input: unknown): boolean {
+    return typeof input === 'object' && input !== null && 'value' in (input as object);
+  },
+};

package/src/index.test.ts

@@ -0,0 +1,273 @@
+/**
+ * End-to-end tests for @hyperfixi/speech.
+ *
+ * Validates:
+ *   1. The plugin installs cleanly via installPlugin()
+ *   2. The parser accepts `speak`, `ask`, `answer` at command position
+ *   3. Runtime execution dispatches to the right commands
+ *   4. speak() uses the Web Speech API (with a mock)
+ *   5. ask() reads from window.prompt (with a mock)
+ *   6. answer sets context.result / context.it
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { speechPlugin, speakCommand, askCommand, answerCommand } from './index';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+interface MockEvaluator {
+  evaluate: (node: any, ctx: any) => Promise<unknown>;
+}
+
+/** Minimal evaluator that returns the literal value or identifier name. */
+const mockEvaluator: MockEvaluator = {
+  async evaluate(node: any) {
+    if (!node) return undefined;
+    if (node.type === 'literal') return node.value;
+    if (node.type === 'identifier') return node.name;
+    return node.value ?? node.name;
+  },
+};
+
+function literal<T>(value: T) {
+  return { type: 'literal', value };
+}
+
+function identifier(name: string) {
+  return { type: 'identifier', name };
+}
+
+// ---------------------------------------------------------------------------
+// Unit-level tests per command
+// ---------------------------------------------------------------------------
+
+describe('speakCommand', () => {
+  let utterances: Array<{
+    text: string;
+    rate?: number;
+    pitch?: number;
+    voice?: SpeechSynthesisVoice | null;
+    volume?: number;
+  }>;
+  let originalSynth: unknown;
+  let originalUtterance: unknown;
+
+  beforeEach(() => {
+    utterances = [];
+    originalSynth = (globalThis as any).speechSynthesis;
+    originalUtterance = (globalThis as any).SpeechSynthesisUtterance;
+
+    (globalThis as any).SpeechSynthesisUtterance = class MockUtterance {
+      text: string;
+      rate = 1;
+      pitch = 1;
+      volume = 1;
+      voice: SpeechSynthesisVoice | null = null;
+      constructor(text: string) {
+        this.text = text;
+      }
+    };
+    (globalThis as any).speechSynthesis = {
+      speak: vi.fn((utter: any) => {
+        utterances.push({
+          text: utter.text,
+          rate: utter.rate,
+          pitch: utter.pitch,
+          voice: utter.voice,
+          volume: utter.volume,
+        });
+      }),
+      getVoices: () => [
+        { name: 'Google UK English Female', lang: 'en-GB' } as SpeechSynthesisVoice,
+      ],
+    };
+  });
+
+  afterEach(() => {
+    (globalThis as any).speechSynthesis = originalSynth;
+    (globalThis as any).SpeechSynthesisUtterance = originalUtterance;
+  });
+
+  it('speaks the text argument via speechSynthesis.speak', async () => {
+    const input = await speakCommand.parseInput(
+      { args: [literal('hello')], modifiers: {} },
+      mockEvaluator,
+      {}
+    );
+    expect(input).toEqual({ text: 'hello' });
+    const ctx: Record<string, unknown> = {};
+    await speakCommand.execute(input, ctx);
+    expect(utterances).toEqual([{ text: 'hello', rate: 1, pitch: 1, voice: null, volume: 1 }]);
+    expect(ctx.result).toBe(true);
+  });
+
+  it('applies `with rate`, `with pitch`, `with volume` options', async () => {
+    const input = await speakCommand.parseInput(
+      {
+        args: [
+          literal('hi'),
+          identifier('with'),
+          identifier('rate'),
+          literal(1.5),
+          identifier('with'),
+          identifier('pitch'),
+          literal(0.8),
+        ],
+        modifiers: {},
+      },
+      mockEvaluator,
+      {}
+    );
+    expect(input).toEqual({ text: 'hi', rate: 1.5, pitch: 0.8 });
+    await speakCommand.execute(input, {});
+    expect(utterances[0].rate).toBe(1.5);
+    expect(utterances[0].pitch).toBe(0.8);
+  });
+
+  it('matches `with voice "<name>"` against available voices', async () => {
+    const input = await speakCommand.parseInput(
+      {
+        args: [
+          literal('hi'),
+          identifier('with'),
+          identifier('voice'),
+          literal('Google UK English Female'),
+        ],
+        modifiers: {},
+      },
+      mockEvaluator,
+      {}
+    );
+    await speakCommand.execute(input, {});
+    expect(utterances[0].voice).toMatchObject({ name: 'Google UK English Female' });
+  });
+
+  it('no-ops when SpeechSynthesis is unavailable (sets result=false)', async () => {
+    (globalThis as any).speechSynthesis = undefined;
+    const ctx: Record<string, unknown> = {};
+    await speakCommand.execute({ text: 'hi' }, ctx);
+    expect(ctx.result).toBe(false);
+  });
+
+  it('throws when text argument is missing', async () => {
+    await expect(
+      speakCommand.parseInput({ args: [], modifiers: {} }, mockEvaluator, {})
+    ).rejects.toThrow(/requires a text argument/);
+  });
+});
+
+describe('askCommand', () => {
+  let originalPrompt: unknown;
+
+  beforeEach(() => {
+    originalPrompt = (globalThis as any).prompt;
+  });
+  afterEach(() => {
+    (globalThis as any).prompt = originalPrompt;
+  });
+
+  it('reads from window.prompt and stores result in context.result and context.it', async () => {
+    (globalThis as any).prompt = vi.fn(() => 'Alice');
+    const input = await askCommand.parseInput(
+      { args: [literal('Your name?')], modifiers: {} },
+      mockEvaluator,
+      {}
+    );
+    expect(input.prompt).toBe('Your name?');
+    const ctx: Record<string, unknown> = {};
+    const out = await askCommand.execute(input, ctx);
+    expect(out).toBe('Alice');
+    expect(ctx.result).toBe('Alice');
+    expect(ctx.it).toBe('Alice');
+  });
+
+  it('returns null when prompt is unavailable', async () => {
+    (globalThis as any).prompt = undefined;
+    const ctx: Record<string, unknown> = {};
+    const out = await askCommand.execute({}, ctx);
+    expect(out).toBeNull();
+  });
+
+  it('honors `with default "value"` syntax', async () => {
+    (globalThis as any).prompt = vi.fn((_p: string, d: string) => d);
+    const input = await askCommand.parseInput(
+      {
+        args: [literal('Your name?'), identifier('with'), identifier('default'), literal('Guest')],
+        modifiers: {},
+      },
+      mockEvaluator,
+      {}
+    );
+    expect(input.defaultValue).toBe('Guest');
+    const ctx: Record<string, unknown> = {};
+    await askCommand.execute(input, ctx);
+    expect(ctx.result).toBe('Guest');
+  });
+});
+
+describe('answerCommand', () => {
+  it('sets context.result and context.it to the given value', async () => {
+    const input = await answerCommand.parseInput(
+      { args: [identifier('with'), literal('programmatic')], modifiers: {} },
+      mockEvaluator,
+      {}
+    );
+    expect(input).toEqual({ value: 'programmatic' });
+    const ctx: Record<string, unknown> = {};
+    await answerCommand.execute(input, ctx);
+    expect(ctx.result).toBe('programmatic');
+    expect(ctx.it).toBe('programmatic');
+  });
+
+  it('accepts bare-value form without leading `with`', async () => {
+    const input = await answerCommand.parseInput(
+      { args: [literal('bare')], modifiers: {} },
+      mockEvaluator,
+      {}
+    );
+    expect(input).toEqual({ value: 'bare' });
+  });
+
+  it('throws without any value', async () => {
+    await expect(
+      answerCommand.parseInput({ args: [], modifiers: {} }, mockEvaluator, {})
+    ).rejects.toThrow(/requires a value/);
+  });
+
+  it('validate() accepts {value: ...} and rejects other shapes', () => {
+    expect(answerCommand.validate({ value: 'x' })).toBe(true);
+    expect(answerCommand.validate(null)).toBe(false);
+    expect(answerCommand.validate({})).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Plugin shape
+// ---------------------------------------------------------------------------
+
+describe('speechPlugin', () => {
+  it('has a valid HyperfixiPlugin shape', () => {
+    expect(speechPlugin.name).toBe('@hyperfixi/speech');
+    expect(typeof speechPlugin.install).toBe('function');
+  });
+
+  it('install() wires three commands into both registries', () => {
+    const commandCalls: Array<{ name: string }> = [];
+    const keywordCalls: string[] = [];
+    const ctx = {
+      commandRegistry: {
+        register: (cmd: any) => commandCalls.push({ name: cmd.name }),
+      },
+      parserExtensions: {
+        registerCommand: (name: string) => keywordCalls.push(name),
+      },
+    } as any;
+
+    speechPlugin.install(ctx);
+
+    expect(keywordCalls.sort()).toEqual(['answer', 'ask', 'speak']);
+    expect(commandCalls.map(c => c.name).sort()).toEqual(['answer', 'ask', 'speak']);
+  });
+});

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @hyperfixi/speech — Web Speech API + prompt() plugin for hyperfixi.
+ *
+ * Adds three commands from upstream _hyperscript 0.9.90:
+ *
+ *   speak "text" [with rate N] [with pitch N] [with voice "Name"]
+ *   ask "prompt"                   → context.result = user's answer
+ *   answer with "text"             → context.result = text (scripted)
+ *
+ * Installation:
+ *
+ * ```ts
+ * import { createRuntime, installPlugin } from '@hyperfixi/core';
+ * import { speechPlugin } from '@hyperfixi/speech';
+ *
+ * const runtime = createRuntime();
+ * installPlugin(runtime, speechPlugin);
+ * ```
+ */
+
+import type { HyperfixiPlugin, HyperfixiPluginContext } from '@hyperfixi/core';
+import { speakCommand, askCommand, answerCommand } from './commands';
+
+export { speakCommand, askCommand, answerCommand };
+export type { SpeakCommandInput, AskCommandInput, AnswerCommandInput } from './commands';
+
+/**
+ * Plugin object for one-shot installation. Registers three command keywords
+ * with the parser and three command implementations with the runtime.
+ *
+ * Idempotent: re-installing in the same process is a no-op for the parser
+ * (keywords are Set-based) and replaces the existing command implementations
+ * with identical ones in the runtime registry.
+ */
+export const speechPlugin: HyperfixiPlugin = {
+  name: '@hyperfixi/speech',
+  install({ commandRegistry, parserExtensions }: HyperfixiPluginContext) {
+    parserExtensions.registerCommand('speak');
+    parserExtensions.registerCommand('ask');
+    parserExtensions.registerCommand('answer');
+    commandRegistry.register(speakCommand as never);
+    commandRegistry.register(askCommand as never);
+    commandRegistry.register(answerCommand as never);
+  },
+};
+
+export default speechPlugin;

package/src/integration.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Real end-to-end integration test: install speechPlugin into an actual
+ * hyperfixi Runtime, parse hyperscript source with the plugin's commands,
+ * and verify execution flows through correctly.
+ *
+ * This is the "round-trip" test the Phase 5 plan called for — proof that
+ * an external plugin package can contribute commands through the public
+ * plugin infrastructure without touching core internals.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { Runtime, installPlugin, getParserExtensionRegistry, parse } from '@hyperfixi/core';
+import { speechPlugin } from './index';
+
+describe('@hyperfixi/speech end-to-end integration', () => {
+  const registry = getParserExtensionRegistry();
+  let baseline: ReturnType<typeof registry.snapshot>;
+  let runtime: Runtime;
+  let originalSynth: unknown;
+  let originalUtterance: unknown;
+  let originalPrompt: unknown;
+  let spoken: string[];
+
+  beforeEach(() => {
+    baseline = registry.snapshot();
+    spoken = [];
+
+    originalSynth = (globalThis as any).speechSynthesis;
+    originalUtterance = (globalThis as any).SpeechSynthesisUtterance;
+    originalPrompt = (globalThis as any).prompt;
+
+    (globalThis as any).SpeechSynthesisUtterance = class MockUtterance {
+      text: string;
+      rate = 1;
+      pitch = 1;
+      volume = 1;
+      voice: SpeechSynthesisVoice | null = null;
+      constructor(text: string) {
+        this.text = text;
+      }
+    };
+    (globalThis as any).speechSynthesis = {
+      speak: (utter: any) => {
+        spoken.push(utter.text);
+      },
+      getVoices: () => [],
+    };
+    (globalThis as any).prompt = vi.fn(() => 'user-typed');
+
+    runtime = new Runtime();
+    installPlugin(runtime, speechPlugin);
+  });
+
+  afterEach(() => {
+    registry.restore(baseline);
+    (globalThis as any).speechSynthesis = originalSynth;
+    (globalThis as any).SpeechSynthesisUtterance = originalUtterance;
+    (globalThis as any).prompt = originalPrompt;
+  });
+
+  it('registers `speak`/`ask`/`answer` as command keywords', () => {
+    expect(registry.hasCommand('speak')).toBe(true);
+    expect(registry.hasCommand('ask')).toBe(true);
+    expect(registry.hasCommand('answer')).toBe(true);
+  });
+
+  it('executes `speak "hello"` through the full parse→runtime pipeline', async () => {
+    // Parser acceptance: importing `parse` from the core entry is the most
+    // convenient way to go from source to AST in the integration layer.
+    const result = parse('speak "hello world"');
+    expect(result.success).toBe(true);
+
+    const el = document.createElement('div');
+    const ctx = {
+      me: el,
+      it: null,
+      you: null,
+      result: null,
+      locals: new Map(),
+      globals: new Map(),
+      variables: new Map(),
+      events: new Map(),
+    } as any;
+
+    await runtime.execute(result.node!, ctx);
+    expect(spoken).toEqual(['hello world']);
+  });
+
+  it('executes `answer with "x"` and sets context.result', async () => {
+    const result = parse('answer with "programmatic"');
+    expect(result.success).toBe(true);
+
+    const el = document.createElement('div');
+    const ctx = {
+      me: el,
+      it: null,
+      you: null,
+      result: null,
+      locals: new Map(),
+      globals: new Map(),
+      variables: new Map(),
+      events: new Map(),
+    } as any;
+
+    await runtime.execute(result.node!, ctx);
+    expect(ctx.result).toBe('programmatic');
+    expect(ctx.it).toBe('programmatic');
+  });
+});