@phoundry/phials-plugin-sdk 1.0.0 → 1.0.2

package/command-types.generated.d.ts

@@ -29,9 +29,9 @@ type CommandContextKey =
 	| "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
+	// Workspace/Collection state
+	| "inWorkspace" // Current directory is a workspace
+	| "hasWorkspaceSelection" // Selected files are in a workspace
 	// Clipboard
 	| "hasClipboard" // Files in clipboard (cut/copy)
 	| "clipboardIsCut" // Clipboard operation is cut
@@ -62,8 +62,8 @@ interface CommandContext {
 	/** Current directory path */
 	currentPath: string;
 
-	/** Whether current directory is a vial */
-	isVial: boolean;
+	/** Whether current directory is a workspace */
+	isWorkspace: boolean;
 
 	/** Whether the saved-views scope has a property schema (e.g. Boards). */
 	hasPropertySchema: boolean;
@@ -143,9 +143,7 @@ interface ContextMenuPlacementConfig extends CommandPlacementBase {
 /**
  * Union of all placement configurations.
  */
-type CommandPlacement =
-	| ToolbarPlacementConfig
-	| ContextMenuPlacementConfig;
+type CommandPlacement = ToolbarPlacementConfig | ContextMenuPlacementConfig;
 
 // ─── Command Definition ──────────────────────────────────────────────────────
 
@@ -257,6 +255,14 @@ interface Command {
 	 */
 	children?: Command[];
 
+	/**
+	 * Optional custom items for menu surfaces that present this command as a
+	 * submenu. Semantic children remain available to the Command Bar.
+	 */
+	submenuItems?: (
+		ctx: CommandContext,
+	) => import("phoundry-ui").MenuItem[];
+
 	// ─── Custom Rendering ─────────────────────────────────────────────────────
 
 	/**

package/events-types.generated.d.ts

@@ -37,7 +37,7 @@ interface EventSubscription {
  */
 type EventHandler<T = unknown> = (payload: T) => void | Promise<void>;
 
-/** Details column layout live-sync payload (ADR-0010). */
+/** Details column layout live-sync payload. */
 interface ColumnLayoutChangedPayload {
 	browsedPath: string;
 	savedViewsCount: number;
@@ -94,22 +94,27 @@ interface CoreEvents {
 	/** Persisted File Note content was created, updated, or removed */
 	"core.file-note.saved": {
 		path: string;
-		vialPath: string;
+		workspacePath: string;
 		hasNote: boolean;
 	};
-	/** Portable Page visibility/order changed for one Vial. */
-	"core.vial-page-config.changed": {
-		vialPath: string;
-		page: VialPageConfig;
+	/** Portable Page visibility/order changed for one Workspace. */
+	"core.workspace-page-config.changed": {
+		workspacePath: string;
+		page: WorkspacePageConfig;
+	};
+	/** Canonical cell deltas or a filtered compatibility refetch for one Workspace. */
+	"core.workspace-values.changed": WorkspaceValuesChangedEvent;
+	/** Workspace Folder Property schemas changed, including paired Relations. */
+	"core.workspace-properties.changed": {
+		workspaceIds: string[];
+		sourcePaneId: string;
 	};
-	/** 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;
+	"core.workspace-formula-output-types.changed": {
+		workspaceId?: string;
+		workspacePath: string;
 		propertyIds: string[];
-		savedViews: SavedVialView[];
+		savedViews: SavedWorkspaceView[];
 		sourcePaneId: string;
 	};
 	/** File opened */
@@ -129,8 +134,8 @@ interface CoreEvents {
 	/** 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[] };
+	/** Known workspaces list changed (add/remove/rename in session) */
+	"core.known-workspaces.changed": { paths: string[] };
 
 	/** Explorer always-hide globs changed */
 	"core.config.hidden-globs.changed": { globs: string[] };

package/file-types.generated.d.ts

@@ -21,6 +21,7 @@ type FileCategory =
 	| "ebook"
 	| "spreadsheet"
 	| "presentation"
+	| "plain text"
 	// Code & Data
 	| "code"
 	| "code - data"
@@ -54,14 +55,16 @@ interface FileEntry {
 	icon?: string;
 	is_file: boolean;
 	is_dir: boolean;
-	is_vial: boolean;
-	/** Nested vial folder when listing inside a parent vial */
-	isChildVial?: boolean;
+	is_workspace: boolean;
+	/** Nested workspace folder when listing inside a parent workspace */
+	isChildWorkspace?: boolean;
 	/** Listing node is a symlink or Windows directory junction */
 	is_symlink?: boolean;
 	/** Resolved absolute target when healthy; stored link text when broken */
 	symlink_target?: string | null;
 	symlink_broken?: boolean;
+	/** Bytes are not local. Set from listing metadata; absent means local or unknown. */
+	online_only?: boolean;
 	size: number;
 	created?: number | null;
 	modified?: number | null;
@@ -91,6 +94,7 @@ type SortOrder = "asc" | "desc";
 type ViewMode =
 	| "details"
 	| "thumbnails"
+	| "masonry"
 	| "column"
 	| "tree"
 	| "boards"
@@ -100,7 +104,7 @@ type ViewMode =
 /** Calendar view zoom level */
 type CalendarScope = "year" | "month" | "week" | "3day" | "day";
 
-/** Built-in calendar date sources (`created`, `modified`) or a vial property id */
+/** Built-in calendar date sources (`created`, `modified`) or a workspace property id */
 type CalendarDateSourceId = "created" | "modified" | (string & {});
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phoundry/phials-plugin-sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Public plugin SDK contract for Phials",
   "type": "module",
   "types": "./phials-plugin-sdk.d.ts",

package/plugin-types.generated.d.ts

@@ -110,6 +110,9 @@ type ProviderType = "preview" | "metadata" | "view" | "module" | "command";
 
 type PreviewDestination = "module" | "gallery" | "page" | "embed";
 
+/** File-mode vs inspection chrome for a Preview surface. Destination still names the host. */
+type PreviewPresentation = "file" | "inspection";
+
 /** Provider-owned state shared by every presentation of one file preview. */
 interface PreviewSession {
 	/** Clean unreferenced sessions are disposed; unresolved work can retain itself. */
@@ -151,6 +154,12 @@ interface PreviewDestinationCapabilities {
 	embed?: boolean;
 }
 
+/** Intrinsic content dimensions reported by a thumbnail provider. */
+interface ThumbnailIntrinsicDimensions {
+	width: number;
+	height: number;
+}
+
 /**
  * Props passed to thumbnail components
  */
@@ -160,6 +169,10 @@ interface ThumbnailProviderProps {
 	size: number;
 	generatedSize?: number;
 	quality?: number;
+	/** Report meaningful rendered dimensions to hosts that support ratio-aware layouts. */
+	onIntrinsicDimensions?: (
+		dimensions: ThumbnailIntrinsicDimensions,
+	) => void;
 }
 
 /**
@@ -321,7 +334,11 @@ interface MetadataColumnPolicy {
 	 */
 	columnWhitelist?: string[];
 
-	/** Whether columns can be auto-shown from file matching alone. Default "when-dominant". */
+	/**
+	 * Whether columns can be auto-shown from file matching alone.
+	 * `"when-dominant"` means uniquely leading in the Folder (match ratio, then
+	 * priority). It does not use the profile `dominant` flag.
+	 */
 	autoVisible?: "never" | "when-any" | "when-dominant";
 
 	/** Fields to show automatically when the provider qualifies. Defaults to the first few schema fields. */
@@ -487,13 +504,13 @@ interface FileBrowserViewProvider {
 	/** Optional: custom column configuration for this view */
 	columns?: ViewColumnDefinition[];
 
-	/** If true, this view is only available in collections (vials) */
+	/** If true, this view is only available in collections (workspaces) */
 	collectionOnly?: boolean;
 
 	/**
 	 * Default item size when a folder has no per-folder override (`itemSize` null).
-	 * Details family uses row-height ticks; thumbnails / gallery use grid ticks;
-	 * Boards uses its column-width ticks.
+	 * Details family uses row-height ticks; Thumbnails, Masonry, and Gallery each
+	 * have their own S/M/L grid ticks; Boards uses its column-width ticks.
 	 */
 	defaultItemSizePreset?: ViewItemSizePreset;
 
@@ -891,6 +908,8 @@ interface PluginSettings {
 	unset(key: string): Promise<void>;
 	/** Remove every durable value and reveal all schema defaults. */
 	reset(): Promise<void>;
+	/** Open the Phials settings window directly to this plugin's settings page. */
+	open(): Promise<void>;
 	onChange(
 		handler: (change: PluginSettingsChange) => void,
 	): PluginSettingsSubscription;
@@ -1082,6 +1101,9 @@ interface EventsAPI {
  * Base Plugin API - available to all providers
  */
 interface PluginAPI {
+	/** Open the Phials settings window directly to this plugin's settings page. */
+	openSettings(): Promise<void>;
+
 	/** Plugin's own settings */
 	settings: PluginSettings;
 

package/public-contract.generated.d.ts

@@ -44,7 +44,7 @@ type PluginPathOutcome =
 			readonly path: string;
 			readonly status: "failed";
 			readonly failure: PluginFileFailure;
-		};
+	  };
 
 interface PluginDirectoryReadResult {
 	readonly entries: readonly FileEntry[];
@@ -61,7 +61,7 @@ type PluginBinaryWriteResult =
 	| {
 			readonly status: "conflict";
 			readonly actualRevision: string | null;
-		};
+	  };
 
 interface FolderSummary {
 	readonly path: string;
@@ -105,6 +105,7 @@ type WorkspaceFolderPropertyType =
 	| "text"
 	| "number"
 	| "date"
+	| "calendar"
 	| "boolean"
 	| "select"
 	| "multi-select"
@@ -117,6 +118,18 @@ type WorkspaceFolderPropertyType =
 
 type WorkspaceFolderPropertyValue = JsonValue;
 
+type WorkspaceFolderCalendarValue =
+	| {
+			readonly kind: "date";
+			readonly start: string;
+			readonly end?: string;
+	  }
+	| {
+			readonly kind: "datetime";
+			readonly start: string;
+			readonly end?: string;
+	  };
+
 interface WorkspaceFolderPropertyOption {
 	readonly id: string;
 	readonly name: string;
@@ -159,9 +172,7 @@ interface WorkspaceFolderPropertyWrite {
 
 interface WorkspaceFoldersAPI {
 	isWorkspaceFolder(path: string): Promise<boolean>;
-	getSchema(
-		workspaceFolderIdOrPath: string,
-	): Promise<WorkspaceFolderSchema>;
+	getSchema(workspaceFolderIdOrPath: string): Promise<WorkspaceFolderSchema>;
 	getPropertyValue(
 		file: WorkspaceFolderFileRef,
 		propertyId: string,
@@ -176,9 +187,22 @@ interface WorkspaceFoldersAPI {
 		values: readonly WorkspaceFolderPropertyWrite[],
 	): Promise<void>;
 	getTags(file: WorkspaceFolderFileRef): Promise<readonly string[]>;
-	setTags(file: WorkspaceFolderFileRef, tags: readonly string[]): Promise<void>;
+	setTags(
+		file: WorkspaceFolderFileRef,
+		tags: readonly string[],
+	): Promise<void>;
 	getRating(file: WorkspaceFolderFileRef): Promise<number | null>;
-	setRating(file: WorkspaceFolderFileRef, rating: number | null): Promise<void>;
+	setRating(
+		file: WorkspaceFolderFileRef,
+		rating: number | null,
+	): Promise<void>;
+	getCalendar(
+		file: WorkspaceFolderFileRef,
+	): Promise<WorkspaceFolderCalendarValue | null>;
+	setCalendar(
+		file: WorkspaceFolderFileRef,
+		value: WorkspaceFolderCalendarValue | null,
+	): Promise<void>;
 	listKnown(): Promise<readonly KnownWorkspaceFolder[]>;
 	openPage(
 		file: WorkspaceFolderFileRef,
@@ -205,11 +229,7 @@ type PluginDatabaseValue = JsonPrimitive | Uint8Array;
 interface PluginDatabaseSchemaOperations {
 	createTable(table: PluginTableDefinition): Promise<void>;
 	addColumn(table: string, column: PluginColumnDefinition): Promise<void>;
-	renameColumn(
-		table: string,
-		from: string,
-		to: string,
-	): Promise<void>;
+	renameColumn(table: string, from: string, to: string): Promise<void>;
 	dropColumn(table: string, column: string): Promise<void>;
 	createIndex(table: string, index: PluginIndexDefinition): Promise<void>;
 	dropIndex(table: string, index: string): Promise<void>;
@@ -271,7 +291,7 @@ interface DetailsViewColumnConfig {
 
 type PagePropertyVisibility = "always" | "not-empty" | "hidden";
 
-interface VialPageConfig {
+interface WorkspacePageConfig {
 	readonly propertyOrder?: readonly string[];
 	readonly propertyVisibility?: Readonly<
 		Record<string, PagePropertyVisibility>
@@ -280,7 +300,7 @@ interface VialPageConfig {
 	readonly fullWidth?: boolean;
 }
 
-interface SavedVialView {
+interface SavedWorkspaceView {
 	readonly id: string;
 	readonly name: string;
 	readonly icon?: string;
@@ -290,38 +310,39 @@ interface SavedVialView {
 }
 
 type PropertyValue = WorkspaceFolderPropertyValue;
-type VialCellDeltaOperation = "set" | "clear" | "pending";
+type WorkspaceCellDeltaOperation = "set" | "clear" | "pending";
 
-interface VialCellDelta {
-	readonly vialId: string;
-	readonly vialPath: string;
+interface WorkspaceCellDelta {
+	readonly workspaceId: string;
+	readonly workspacePath: string;
 	readonly fileId: string;
 	readonly filePath: string;
 	readonly propertyId: string;
-	readonly operation: VialCellDeltaOperation;
+	readonly operation: WorkspaceCellDeltaOperation;
 	readonly value: PropertyValue | null;
 	readonly mutationVersion: number;
 }
 
-interface VialValueDeltaEvent {
+interface WorkspaceValueDeltaEvent {
 	readonly kind: "delta";
 	readonly sourcePaneId: string;
-	readonly cell: VialCellDelta;
-	readonly dependentDeltas: readonly VialCellDelta[];
+	readonly cell: WorkspaceCellDelta;
+	readonly dependentDeltas: readonly WorkspaceCellDelta[];
 }
 
-interface VialValueRefetchEvent {
+interface WorkspaceValueRefetchEvent {
 	readonly kind: "refetch";
 	readonly sourcePaneId: string;
-	readonly vialId: string;
-	readonly vialPath: string;
+	readonly workspaceId: string;
+	readonly workspacePath: string;
 	readonly fileIds?: readonly string[];
 	readonly filePaths?: readonly string[];
 	readonly propertyIds?: readonly string[];
 	readonly reason: "legacy" | "plugin" | "schema";
 }
 
-type VialValuesChangedEvent = VialValueDeltaEvent | VialValueRefetchEvent;
+type WorkspaceValuesChangedEvent =
+	WorkspaceValueDeltaEvent | WorkspaceValueRefetchEvent;
 
 type DrivesChangedPayload = {
 	readonly reason: "mounted" | "unmounted" | "changed" | "poll";