@phoundry/phials-plugin-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phoundry Lab
+
+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,3 @@
+# @phoundry/phials-plugin-sdk
+
+Generated public Plugin API contract for Phials. Do not edit this package output directly.

package/command-types.generated.d.ts

@@ -0,0 +1,288 @@
+// @generated from phials - do not edit
+// Source graph: phials/scripts/lib/public-sdk-manifest.mjs
+
+/// <reference path="./pane-context.generated.d.ts" />
+
+/**
+ * Command System Type Definitions
+ *
+ * Defines interfaces for the unified command architecture including:
+ * - Context keys for fast filtering
+ * - Command definition and configuration
+ * - UI placement configuration
+ * - User settings persistence
+ */
+
+// ─── Context Keys (Fast Pre-Filter) ──────────────────────────────────────────
+
+/**
+ * Context keys for fast command filtering.
+ * Commands declare which keys they require, and the CommandManager
+ * maintains the current set of active keys based on app state.
+ */
+type CommandContextKey =
+	// Selection state
+	| "hasSelection" // Any file(s) selected
+	| "hasSingleSelection" // Exactly one file selected
+	| "hasMultiSelection" // 2+ files selected
+	// File type (based on selection)
+	| "selectionIsFile" // All selected are files
+	| "selectionIsDirectory" // All selected are directories
+	| "selectionIsMixed" // Mix of files and directories
+	// Vial/Collection state
+	| "inVial" // Current directory is a vial
+	| "hasVialSelection" // Selected files are in a vial
+	// Clipboard
+	| "hasClipboard" // Files in clipboard (cut/copy)
+	| "clipboardIsCut" // Clipboard operation is cut
+	| "clipboardIsCopy" // Clipboard operation is copy
+	| "clipboardIsCopySymlink" // Clipboard operation is copy-as-symlink
+	// Navigation state
+	| "canGoBack" // Navigation history has back
+	| "canGoForward" // Navigation history has forward
+	// Always
+	| "always"; // No filtering (always visible)
+
+// ─── Command Context ─────────────────────────────────────────────────────────
+
+/**
+ * Runtime context passed to command handlers and predicates.
+ * Built from the active pane's current state.
+ */
+interface CommandContext {
+	/** The active pane (always available) */
+	pane: PluginPaneContext;
+
+	/** Selected files (empty if none) */
+	selectedFiles: FileEntry[];
+
+	/** The "target" file (for context menu: right-clicked file; otherwise: first selected) */
+	targetFile: FileEntry | null;
+
+	/** Current directory path */
+	currentPath: string;
+
+	/** Whether current directory is a vial */
+	isVial: boolean;
+
+	/** Whether the saved-views scope has a property schema (e.g. Boards). */
+	hasPropertySchema: boolean;
+
+	/** Active context keys (for debugging/inspection) */
+	activeContextKeys: ReadonlySet<CommandContextKey>;
+}
+
+// ─── Command Shortcut ────────────────────────────────────────────────────────
+
+/**
+ * Keyboard shortcut configuration for a command.
+ */
+interface CommandShortcut {
+	/** Default shortcut(s) - up to 3 */
+	defaults?: ShortcutDefinition[];
+
+	/** If true, don't call preventDefault() after handling */
+	allowDefault?: boolean;
+
+	/** Priority for conflict resolution (higher = checked first) */
+	priority?: number;
+}
+
+// ─── Command Placements ──────────────────────────────────────────────────────
+
+/**
+ * Areas where commands can be placed in the UI.
+ */
+type CommandPlacementArea = "toolbar" | "contextMenu";
+
+/**
+ * Base placement configuration.
+ */
+interface CommandPlacementBase {
+	area: CommandPlacementArea;
+}
+
+/**
+ * Toolbar placement configuration (PathBar toolbar).
+ */
+interface ToolbarPlacementConfig extends CommandPlacementBase {
+	area: "toolbar";
+	/** Icon override for toolbar display */
+	icon?: string | ((ctx: CommandContext) => string);
+	/** Order priority (higher = more left) */
+	priority?: number;
+	/** If true, cannot be removed by user */
+	fixed?: boolean;
+	/** Whether to show text label by default (can be overridden by user config) */
+	showLabel?: boolean;
+	/** Whether to show the dropdown chevron on commands with children (default true) */
+	showArrow?: boolean;
+	/** Toggle/active state indicator */
+	active?: (ctx: CommandContext) => boolean;
+	/** Optional activity badge count on the path bar button */
+	badgeCount?: (ctx: CommandContext) => number;
+	/** Optional sub-toolbar component shown when button is toggled */
+	subToolbar?: import("svelte").Component<{ ctx: ToolbarContext }>;
+}
+
+/**
+ * Context menu placement configuration.
+ */
+interface ContextMenuPlacementConfig extends CommandPlacementBase {
+	area: "contextMenu";
+	/** Selection mode this applies to */
+	selectionMode?: "single" | "multi" | "both";
+	/** Default submenu (null = root level) */
+	submenu?: { id: string; label: string; icon?: string } | null;
+	/** Show as dangerous (red styling) */
+	danger?: boolean;
+	/** Order within section/submenu (lower = higher in menu) */
+	order?: number;
+}
+
+/**
+ * Union of all placement configurations.
+ */
+type CommandPlacement =
+	| ToolbarPlacementConfig
+	| ContextMenuPlacementConfig;
+
+// ─── Command Definition ──────────────────────────────────────────────────────
+
+/**
+ * A command is a discrete action that can be invoked via:
+ * - Keyboard shortcut
+ * - Command bar
+ * - Context menu
+ * - Toolbar button
+ * - Programmatically
+ */
+interface CommandPresentation {
+	label?: string;
+	description?: string;
+	tooltip?: string;
+	icon?: string;
+	searchAliases?: string[];
+}
+
+interface Command {
+	/** Unique command identifier (e.g., 'core.file.delete', 'plugin.terminal.toggle') */
+	id: string;
+
+	/** Human-readable label */
+	label: string;
+
+	/** Optional description for command bar/settings */
+	description?: string;
+
+	/** Tooltip text shown on hover (defaults to label if not set) */
+	tooltip?: string;
+
+	/** Icon for UI display */
+	icon?: string;
+
+	// ─── Visibility & Availability ─────────────────────────────────────────────
+
+	/**
+	 * Context keys required for this command to be visible.
+	 * Used for fast pre-filtering before evaluating `when()`.
+	 * If omitted or contains 'always', command is always considered.
+	 */
+	contextKeys?: CommandContextKey[];
+
+	/**
+	 * Fine-grained visibility check.
+	 * Only called if contextKeys pass (or are not specified).
+	 * Return false to hide the command.
+	 */
+	when?: (ctx: CommandContext) => boolean;
+
+	/**
+	 * Whether the command is disabled (visible but not executable).
+	 * Return true to disable.
+	 */
+	disabled?: (ctx: CommandContext) => boolean;
+
+	/** Dynamic display metadata for runtime surfaces; never changes availability. */
+	presentation?: (ctx: CommandContext) => CommandPresentation;
+
+	// ─── Execution ─────────────────────────────────────────────────────────────
+
+	/** The action to execute */
+	action: (ctx: CommandContext) => void | Promise<void>;
+
+	/**
+	 * Optional toast shown after the action completes successfully (no throw).
+	 * Static entry or a function of the same context passed to `action`.
+	 */
+	toastData?:
+		| import("phoundry-ui").ToastEntry
+		| ((
+				ctx: CommandContext,
+		  ) => import("phoundry-ui").ToastEntry | null | undefined);
+
+	// ─── Keyboard Shortcut ─────────────────────────────────────────────────────
+
+	/** Keyboard shortcut configuration */
+	shortcut?: CommandShortcut;
+
+	// ─── Default UI Placements ─────────────────────────────────────────────────
+
+	/**
+	 * Where this command appears by default.
+	 * Users can override these in settings.
+	 */
+	defaultPlacements?: CommandPlacement[];
+
+	// ─── Command Bar ───────────────────────────────────────────────────────────
+
+	/**
+	 * Category for grouping in command bar.
+	 * E.g., 'File', 'Edit', 'View', 'Navigation', 'Tabs'
+	 */
+	category?: string;
+
+	/** Alternative search terms for command bar fuzzy search */
+	searchAliases?: string[];
+
+	/** Optional group for path bar dropdown separators between sibling child commands */
+	menuGroup?: string;
+
+	// ─── Child Commands ───────────────────────────────────────────────────────
+
+	/**
+	 * Child commands for dropdown/submenu patterns.
+	 * When a command has children, its action typically does nothing
+	 * and the UI shows a dropdown menu of child commands instead.
+	 */
+	children?: Command[];
+
+	// ─── Custom Rendering ─────────────────────────────────────────────────────
+
+	/**
+	 * Custom render snippet for context menu.
+	 * When provided, the command renders as a custom menu item instead of
+	 * a standard action item. Useful for inline controls like ratings.
+	 *
+	 * @returns A Svelte Snippet to render in the menu
+	 */
+	renderSnippet?: (ctx: CommandContext) => import("svelte").Snippet;
+}
+
+// ─── Command Provider ────────────────────────────────────────────────────────
+
+/**
+ * A command provider contributes commands from a plugin.
+ */
+interface CommandProvider {
+	type: "command";
+
+	/** Provider identifier */
+	id: string;
+
+	/** Human-readable name */
+	name: string;
+
+	/** Commands contributed by this provider */
+	commands: Command[];
+}

package/events-types.generated.d.ts

@@ -0,0 +1,195 @@
+// @generated from phials - do not edit
+// Source graph: phials/scripts/lib/public-sdk-manifest.mjs
+
+/**
+ * Event System Type Definitions
+ *
+ * Defines types for the pub/sub event system used for cross-plugin
+ * communication and internal app events.
+ */
+
+// ─── Event Definition ────────────────────────────────────────────────────────
+
+/**
+ * Event type definition - registered for introspection/validation
+ */
+interface EventDefinition<T = unknown> {
+	/** Unique event ID (e.g., 'core.navigation.changed', 'phials.terminal.command-executed') */
+	id: string;
+	/** Optional description for docs/debugging */
+	description?: string;
+	/** First Plugin API version that exposes this event. */
+	sincePluginApiVersion: string;
+	/** Plugin owner for custom events; core events have no plugin owner. */
+	pluginId?: string;
+}
+
+/**
+ * Subscription handle for cleanup
+ */
+interface EventSubscription {
+	/** Unsubscribe from the event */
+	unsubscribe(): void;
+}
+
+/**
+ * Event handler callback type
+ */
+type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
+
+/** Details column layout live-sync payload (ADR-0010). */
+interface ColumnLayoutChangedPayload {
+	browsedPath: string;
+	savedViewsCount: number;
+	activeSavedViewId: string | null;
+	columnConfig: DetailsViewColumnConfig[];
+	calculationRowVisible: boolean;
+	sourcePaneId: string;
+}
+
+type LayoutSettledReason =
+	| "center-divider"
+	| "center-structure"
+	| "panel-resize"
+	| "panel-structure"
+	| "panel-transition"
+	| "window-resize"
+	| "window-restore";
+
+/** Semantic notification emitted after shell-owned geometry reaches the DOM. */
+interface LayoutSettledPayload {
+	reasons: LayoutSettledReason[];
+	affectedIds: string[];
+	timestamp: number;
+}
+
+// ─── Core Events ─────────────────────────────────────────────────────────────
+
+/**
+ * Built-in core events (strongly typed)
+ */
+interface CoreEvents {
+	/** Pane navigation path changed */
+	"core.navigation.changed": { path: string; paneId: string };
+
+	/** File selection changed in a pane */
+	"core.selection.changed": { paths: string[]; paneId: string };
+
+	/** New tab created */
+	"core.tab.created": { tabId: string };
+
+	/** Tab closed */
+	"core.tab.closed": { tabId: string };
+
+	/** Active tab changed */
+	"core.tab.switched": { tabId: string; previousTabId: string };
+
+	/** File or directory renamed */
+	"core.file.renamed": { oldPath: string; newPath: string };
+
+	/** Files deleted */
+	"core.file.deleted": { paths: string[] };
+	/** File saved */
+	"core.file.saved": { path: string };
+	/** Persisted File Note content was created, updated, or removed */
+	"core.file-note.saved": {
+		path: string;
+		vialPath: string;
+		hasNote: boolean;
+	};
+	/** Portable Page visibility/order changed for one Vial. */
+	"core.vial-page-config.changed": {
+		vialPath: string;
+		page: VialPageConfig;
+	};
+	/** Canonical cell deltas or a filtered compatibility refetch for one Vial. */
+	"core.vial-values.changed": VialValuesChangedEvent;
+	/** Formula output types changed; every pane must normalize its consumers. */
+	"core.vial-formula-output-types.changed": {
+		vialId?: string;
+		vialPath: string;
+		propertyIds: string[];
+		savedViews: SavedVialView[];
+		sourcePaneId: string;
+	};
+	/** File opened */
+	"core.file.opened": { path: string };
+	/** File created */
+	"core.file.created": { path: string };
+
+	/** Directory contents changed (files added/removed/modified) */
+	"core.directory.changed": { path: string; paneId: string };
+	/** Directory renamed */
+	"core.directory.renamed": { oldPath: string; newPath: string };
+	/** Directory deleted */
+	"core.directory.deleted": { path: string };
+	/** Directory created */
+	"core.directory.created": { path: string };
+
+	/** App setting value changed */
+	"core.settings.changed": { key: string; value: unknown };
+
+	/** Known vials list changed (add/remove/rename in session) */
+	"core.known-vials.changed": { paths: string[] };
+
+	/** Explorer always-hide globs changed */
+	"core.config.hidden-globs.changed": { globs: string[] };
+
+	/** Global audio: current track or index changed */
+	"core.audio.track.changed": {
+		trackId: string | null;
+		path: string | null;
+		index: number;
+	};
+
+	/** Global audio: queue contents changed */
+	"core.audio.queue.changed": { trackIds: string[]; length: number };
+
+	/** Global audio: playback error (e.g. decode / missing file) */
+	"core.audio.playback.error": { trackId: string | null; message: string };
+
+	/** Drive/volume set may have changed (after pane drive caches refreshed) */
+	"core.drives.changed": DrivesChangedPayload;
+
+	/** Details column layout changed in a pane (path-owned or saved-view-owned) */
+	"core.columns.layout.changed": ColumnLayoutChangedPayload;
+
+	/** Shell-owned geometry changed and presented consumers may measure locally. */
+	"core.layout.settled": LayoutSettledPayload;
+}
+
+// ─── Plugin Events ───────────────────────────────────────────────────────────
+
+/**
+ * Plugin event map - plugins extend this via declaration merging.
+ *
+ * @example
+ * ```typescript
+ * // In a plugin file:
+ * declare global {
+ *   interface PluginEvents {
+ *     'phials.terminal.command-executed': {
+ *       command: string;
+ *       exitCode: number;
+ *       duration: number;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface PluginEvents {
+	// Plugins add their events here via module augmentation
+}
+
+// ─── Combined Event Map ──────────────────────────────────────────────────────
+
+/**
+ * Combined event map for type safety.
+ * Merges CoreEvents and PluginEvents.
+ */
+type EventMap = CoreEvents & PluginEvents;
+
+/**
+ * Helper type to get event payload for a given event ID
+ */
+type EventPayload<K extends keyof EventMap> = EventMap[K];