@fungi.computer/nacre 0.0.3 → 0.1.1

package/dist/app-directory.d.ts

@@ -105,7 +105,7 @@ export declare const appDirectoryEntrySchema: z.ZodObject<{
             agent?: (Readonly<{
                 order?: number | undefined;
             }> & Readonly<{
-                keybind?: string | undefined;
+                keybind? /** The selected Computers and what the App may do on each. */: string | undefined;
             }>) | undefined;
             help?: Readonly<{
                 order?: number | undefined;
@@ -298,7 +298,7 @@ export declare const appDirectoryResponseSchema: z.ZodLazy<z.ZodObject<{
                 agent?: (Readonly<{
                     order?: number | undefined;
                 }> & Readonly<{
-                    keybind?: string | undefined;
+                    keybind? /** The selected Computers and what the App may do on each. */: string | undefined;
                 }>) | undefined;
                 help?: Readonly<{
                     order?: number | undefined;

package/dist/command-host.d.ts

@@ -58,11 +58,26 @@ export type AppCommandDeclaration = Readonly<{
     }>>;
 }>;
 import type { AppHostHandlers, AppHostReservedChord } from "@fungi.computer/agar/host";
-import { type WhistleExecutionInput, type WhistleExecutionOutcome, type WhistleContributionLease, type WhistleCommand, type WhistleMenuProjection, type WhistleRuntime, type WhistleSnapshot } from "@fungi.computer/whistle";
+import { type WhistleExecutionInput, type WhistleExecutionOutcome, type WhistleContributionLease, type WhistleCommand, type WhistleCommandKey, type WhistleMenuProjection, type WhistleProjectionRow, type WhistleRuntime, type WhistleSnapshot } from "@fungi.computer/whistle";
 /** Select the shell command-palette chord for a Mac or non-Mac keyboard. */
 export declare function commandPaletteReservedChordForPlatform(mac: boolean): AppHostReservedChord;
 /** Select the shell command-palette chord from the embedding browser user agent. */
 export declare function commandPaletteReservedChordForUserAgent(userAgent: string): AppHostReservedChord;
+/** One App command, named by its surface and its declared command id. */
+export type AppCommandTarget = Readonly<{
+    /** The App surface, such as `installation:inkcap`. */
+    surfaceId: string;
+    /** The command id the App's Release declares. */
+    commandId: string;
+}>;
+/**
+ * The typed Whistle identity of a command a mounted App surface contributed:
+ * each mounted surface owns the Whistle namespace named by its surface id.
+ *
+ * @param target - The App surface and its declared command id.
+ * @returns The key every snapshot row of that command carries as `command`.
+ */
+export declare function appSurfaceCommandKey(target: AppCommandTarget): WhistleCommandKey;
 /** Whistle source of Release-advertised rows for Apps not yet mounted. */
 export declare const appDirectorySourceId = "app-directory";
 /** The command side of one mounted App's host handlers. */
@@ -76,10 +91,19 @@ export type AppSurfaceCommandMount = Readonly<{
 }>;
 /** Commands owned by one pane, projected to globals plus its focus scope. */
 export type PaneCommands = Readonly<{
-    /** Qualify a locally contributed id in this pane's own namespace. */
-    commandId: (id: string) => string;
-    /** Contribute or replace commands owned by this pane through the returned lease. */
-    contribute: (commands: readonly WhistleCommand<never>[]) => WhistleContributionLease;
+    /**
+     * The key of a command this pane contributed.
+     *
+     * @param id - The command's local id.
+     * @param group - The group it was contributed under, if any.
+     */
+    command: (id: string, group?: string) => WhistleCommandKey;
+    /**
+     * Contribute or replace commands owned by this pane through the returned
+     * lease. A group gives one embedded source (such as a Parakeet contribution)
+     * its own namespace inside the pane, so its ids never collide with others.
+     */
+    contribute: (commands: readonly WhistleCommand<never>[], group?: string) => WhistleContributionLease;
     /** Run a command by id. */
     execute: WhistleRuntime["execute"];
     /** Read the commands and bindings currently available. */
@@ -110,6 +134,11 @@ export type AppSurfaceCommandHost = Readonly<{
         appTitle: string;
         command: AppCommandDeclaration;
     }>[], run: (surfaceId: string, commandId: string) => Promise<void>) => () => void;
+    /**
+     * The App command a snapshot row runs: a mounted App's own row, or a
+     * directory row that opens its App first. Shell and pane rows have none.
+     */
+    readonly appCommand: (row: Pick<WhistleProjectionRow, "command" | "sourceId">) => AppCommandTarget | undefined;
     /** Read the menu rows belonging to the focused App. */
     readonly menu: () => readonly WhistleMenuProjection[];
     /**
@@ -118,7 +147,7 @@ export type AppSurfaceCommandHost = Readonly<{
      */
     readonly active: () => WhistleSnapshot;
     /** Execute an active row, an agent row, or an exact programmatic action. */
-    readonly execute: (commandId: string, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
+    readonly execute: (command: WhistleCommandKey, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
     /** Read the complete renderer-neutral graph for host consumers. */
     readonly snapshot: () => WhistleSnapshot;
     /** Observe graph changes, including contribution replacement and disposal. */

package/dist/command-host.js

@@ -1,6 +1,11 @@
 import { AppError } from "@fungi.computer/agar/errors";
-import { createWhistle, scopeSnapshot, } from "@fungi.computer/whistle";
+import { createWhistle, sameWhistleCommand, scopeSnapshot, } from "@fungi.computer/whistle";
 const emptyMenu = Object.freeze([]);
+/** The shell command an App's reserved command-palette chord runs. */
+const commandPaletteCommand = Object.freeze({
+    namespace: "shell",
+    id: "show-command-palette",
+});
 const commandPaletteReservedChord = Object.freeze({
     altKey: false,
     ctrlKey: false,
@@ -21,6 +26,16 @@ export function commandPaletteReservedChordForPlatform(mac) {
 export function commandPaletteReservedChordForUserAgent(userAgent) {
     return commandPaletteReservedChordForPlatform(/Mac|iPhone|iPad/u.test(userAgent));
 }
+/**
+ * The typed Whistle identity of a command a mounted App surface contributed:
+ * each mounted surface owns the Whistle namespace named by its surface id.
+ *
+ * @param target - The App surface and its declared command id.
+ * @returns The key every snapshot row of that command carries as `command`.
+ */
+export function appSurfaceCommandKey(target) {
+    return Object.freeze({ namespace: target.surfaceId, id: target.commandId });
+}
 /** Whistle source of Release-advertised rows for Apps not yet mounted. */
 export const appDirectorySourceId = "app-directory";
 /** Bindings an App may never claim: the leader chord crosses every iframe. */
@@ -154,7 +169,7 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
         }
         return {
             sourceId: mount.id,
-            namespace: encodeURIComponent(mount.id),
+            namespace: mount.id,
             scope: mount.id,
             commands: commands.map((command) => {
                 // Agar carries a static availability fact; Whistle evaluates availability
@@ -231,7 +246,9 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                 throw new Error("App reserved chord is unavailable");
             if (input.repeat)
                 return;
-            const outcome = await execute(input.id, { origin: "browser" });
+            const outcome = await execute(commandPaletteCommand, {
+                origin: "browser",
+            });
             if (outcome.status !== "handled")
                 throw new Error("App reserved chord could not run");
         };
@@ -247,11 +264,11 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
         });
         const agentCommands = Object.freeze({
             snapshot: agentSnapshot,
-            execute: (commandId, input) => {
+            execute: (command, input) => {
                 if (input.origin !== "agent" ||
-                    !agentSnapshot().agent.some((row) => row.commandId === commandId))
+                    !agentSnapshot().agent.some((row) => sameWhistleCommand(row.command, command)))
                     return Promise.resolve({ status: "missing" });
-                return execute(commandId, input);
+                return execute(command, input);
             },
         });
         return Object.freeze({
@@ -277,7 +294,9 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
             throw new Error("Pane command mount ID must not be blank");
         if (mounts.has(paneId) || panes.has(paneId))
             throw new Error("Pane command mount ID is already active");
-        const namespace = `pane-${encodeURIComponent(paneId)}`;
+        const namespace = `pane:${paneId}`;
+        // A group is a namespace nested under the pane's own.
+        const groupNamespace = (group) => group === undefined ? namespace : `${namespace}/${group}`;
         const ownedCommands = new Map();
         const state = {
             disposed: false,
@@ -317,16 +336,18 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                         throw new Error("Pane commands cannot bind the reserved leader chord");
         };
         return Object.freeze({
-            commandId: (id) => `${namespace}:${id}`,
-            contribute: (commands) => {
+            command: (id, group) => Object.freeze({ namespace: groupNamespace(group), id }),
+            contribute: (commands, group) => {
                 assertPaneLive();
                 checkBindings(commands);
+                const contributed = groupNamespace(group);
                 const underlying = whistle.contribute({
                     sourceId: `pane:${paneId}`,
-                    namespace,
+                    namespace: contributed,
                     scope: paneId,
                     commands,
                 });
+                const keys = (next) => next.map((command) => Object.freeze({ namespace: contributed, id: command.id }));
                 let active = true;
                 const lease = Object.freeze({
                     update: (replacement) => {
@@ -334,7 +355,7 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                             return;
                         checkBindings(replacement);
                         underlying.update(replacement);
-                        ownedCommands.set(lease, new Set(replacement.map((command) => `${namespace}:${command.id}`)));
+                        ownedCommands.set(lease, keys(replacement));
                     },
                     dispose: () => {
                         if (!active)
@@ -346,10 +367,10 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                     },
                 });
                 state.leases.add(lease);
-                ownedCommands.set(lease, new Set(commands.map((command) => `${namespace}:${command.id}`)));
+                ownedCommands.set(lease, keys(commands));
                 return lease;
             },
-            execute: (commandId, input) => {
+            execute: (command, input) => {
                 const snapshot = state.snapshot;
                 const rows = input.origin === "agent"
                     ? [snapshot.agent]
@@ -364,16 +385,16 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                 // A catalog action can be callable from an admitted row without a menu
                 // or palette projection. Its contribution still belongs to this pane.
                 const owned = input.origin !== "agent" &&
-                    [...ownedCommands.values()].some((ids) => ids.has(commandId));
+                    [...ownedCommands.values()].some((keys) => keys.some((key) => sameWhistleCommand(key, command)));
                 const admitted = owned ||
-                    rows.some((projection) => projection.some((row) => row.commandId === commandId));
+                    rows.some((projection) => projection.some((row) => sameWhistleCommand(row.command, command)));
                 const human = input.origin !== "programmatic" && input.origin !== "agent";
                 if (state.disposed ||
                     disposed ||
                     !admitted ||
                     (human && focusedMount !== paneId))
                     return Promise.resolve({ status: "missing" });
-                return whistle.execute(commandId, input);
+                return whistle.execute(command, input);
             },
             snapshot: () => state.snapshot,
             subscribe: (listener) => {
@@ -432,18 +453,24 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
                 shellContribution = undefined;
         };
     };
+    // Directory rows share one namespace; each row's local id is an opaque
+    // index whose App command target this map holds.
+    let directoryTargets = new Map();
     const registerDirectoryCommands = (rows, run) => {
         assertLive();
         directoryContribution?.dispose();
+        const targets = new Map();
         const contribution = whistle.contribute({
             sourceId: appDirectorySourceId,
-            namespace: "app-directory",
-            commands: rows.flatMap(({ surfaceId, appTitle, command }) => {
+            namespace: appDirectorySourceId,
+            commands: rows.flatMap(({ surfaceId, appTitle, command }, index) => {
                 const palette = command.projections?.palette;
                 if (palette === undefined)
                     return [];
+                const id = `entry-${String(index)}`;
+                targets.set(id, Object.freeze({ surfaceId, commandId: command.id }));
                 const projected = {
-                    id: `${encodeURIComponent(surfaceId)}-${encodeURIComponent(command.id)}`,
+                    id,
                     title: command.title,
                     category: `${appTitle} · ${command.category}`,
                     projections: {
@@ -457,32 +484,44 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
             }),
         });
         directoryContribution = contribution;
+        directoryTargets = targets;
         let active = true;
         return () => {
             if (!active)
                 return;
             active = false;
             contribution.dispose();
-            if (directoryContribution === contribution)
+            if (directoryContribution === contribution) {
                 directoryContribution = undefined;
+                directoryTargets = new Map();
+            }
         };
     };
+    const appCommand = (row) => {
+        if (row.sourceId === appDirectorySourceId)
+            return row.command.namespace === appDirectorySourceId
+                ? directoryTargets.get(row.command.id)
+                : undefined;
+        return mounts.has(row.sourceId) && row.command.namespace === row.sourceId
+            ? Object.freeze({ surfaceId: row.sourceId, commandId: row.command.id })
+            : undefined;
+    };
     const menu = () => focusedMenu;
-    const isActive = (commandId) => {
+    const isActive = (command) => {
         const { bindings, palette, slash, help, menu: rows } = activeSnapshot;
-        return [bindings, palette, slash, help, rows].some((projection) => projection.some((row) => row.commandId === commandId));
+        return [bindings, palette, slash, help, rows].some((projection) => projection.some((row) => sameWhistleCommand(row.command, command)));
     };
-    const execute = async (commandId, input) => {
+    const execute = async (command, input) => {
         if (input.origin === "agent" &&
             !whistle
                 .snapshot()
-                .agent.some((command) => command.commandId === commandId))
+                .agent.some((row) => sameWhistleCommand(row.command, command)))
             return { status: "missing" };
         if (input.origin !== "programmatic" &&
             input.origin !== "agent" &&
-            !isActive(commandId))
+            !isActive(command))
             return { status: "missing" };
-        return whistle.execute(commandId, input);
+        return whistle.execute(command, input);
     };
     const dispose = () => {
         if (disposed)
@@ -501,6 +540,7 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
         shellContribution = undefined;
         directoryContribution?.dispose();
         directoryContribution = undefined;
+        directoryTargets = new Map();
         mounts.clear();
         focusedMount = null;
         focusedMenu = emptyMenu;
@@ -515,6 +555,7 @@ export function createAppSurfaceCommandHost(whistle = createWhistle()) {
         focus,
         registerShellCommands,
         registerDirectoryCommands,
+        appCommand,
         menu,
         active: () => activeSnapshot,
         execute,

package/dist/keys.d.ts

@@ -1,4 +1,4 @@
-import type { WhistleBindingProjection, WhistleExecutionInput, WhistleExecutionOutcome, WhistleSnapshot } from "@fungi.computer/whistle";
+import type { WhistleBindingProjection, WhistleCommandKey, WhistleExecutionInput, WhistleExecutionOutcome, WhistleSnapshot } from "@fungi.computer/whistle";
 /** One physical chord parsed from a Whistle binding such as `alt+left`. */
 export type ShellChord = Readonly<{
     /** The key's normalized name, such as left or escape. */
@@ -37,7 +37,7 @@ export type ShellKeyHost = Readonly<{
     /** Observe command changes; call the returned disposer to stop listening. */
     subscribe: (listener: () => void) => () => void;
     /** Run a command through the host with the original input origin. */
-    execute: (commandId: string, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
+    execute: (command: WhistleCommandKey, input: WhistleExecutionInput) => Promise<WhistleExecutionOutcome>;
 }>;
 /**
  * Dispatch the active view's single-chord bindings from the shell document.

package/dist/keys.js

@@ -103,9 +103,9 @@ function isEditing(event) {
 export function installShellKeys(root, host, mac) {
     let chords = [];
     const refresh = () => {
-        chords = host.active().bindings.flatMap(({ binding, commandId }) => {
+        chords = host.active().bindings.flatMap(({ binding, command }) => {
             const chord = parseChord(binding, mac);
-            return chord === null ? [] : [{ commandId, chord }];
+            return chord === null ? [] : [{ command, chord }];
         });
     };
     const onKeyDown = (event) => {
@@ -117,7 +117,7 @@ export function installShellKeys(root, host, mac) {
             return;
         event.preventDefault();
         void host
-            .execute(match.commandId, { origin: "keyboard" })
+            .execute(match.command, { origin: "keyboard" })
             .catch((cause) => {
             console.warn("Shell key command failed", cause);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/nacre",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "author": "Levi <levi@technomancy.dev>",
   "description": "The shell client for hosting Apps: workbench, command host, keys, commands, window manager and App directory rows",
   "type": "module",
@@ -52,11 +52,11 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@fungi.computer/agar": "0.4.0",
+    "@fungi.computer/agar": "0.6.0",
     "@fungi.computer/ear-tag": "0.1.0",
     "@fungi.computer/gills": "0.2.0",
-    "@fungi.computer/puffball": "0.2.0",
-    "@fungi.computer/whistle": "0.2.0",
+    "@fungi.computer/puffball": "0.3.0",
+    "@fungi.computer/whistle": "0.3.0",
     "effect": "4.0.2",
     "zod": "4.4.3"
   },