@phoundry/phials-plugin-sdk 1.0.1 → 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 ──────────────────────────────────────────────────────
 

package/events-types.generated.d.ts

@@ -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;
@@ -101,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.1",
+  "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. */
@@ -331,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. */
@@ -497,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 / Masonry / 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;
 
@@ -901,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;
@@ -1092,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

@@ -291,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>
@@ -300,7 +300,7 @@ interface VialPageConfig {
 	readonly fullWidth?: boolean;
 }
 
-interface SavedVialView {
+interface SavedWorkspaceView {
 	readonly id: string;
 	readonly name: string;
 	readonly icon?: string;
@@ -310,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";