@punica/editor 1.6.12 → 1.6.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.6.12",
+  "version": "1.6.14",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

package/types/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="punica.module.shell.activityBar.d.ts" />
+/// <reference path="punica.module.shell.appBar.d.ts" />
 /// <reference path="punica.module.shell.keyboardShortcuts.d.ts" />
 /// <reference path="punica.module.shell.dragDrop.d.ts" />
 /// <reference path="punica.module.shell.layout.d.ts" />

package/types/punica.module.runtime.fs.d.ts

@@ -192,6 +192,22 @@ declare module 'punica' {
        */
       cwd?: string;
 
+      /**
+       * Is a concrete provider installed behind this facade?
+       *
+       * **Substrate-provided — hosts must NOT implement this.** It exists only
+       * on the wrapper the substrate hands out as `punica.runtime.fs`, which is
+       * why it is optional: reading it off a raw provider object yields
+       * `undefined`, and a caller should treat that as "cannot tell, fall back".
+       *
+       * Answers without any filesystem access. Before it existed, the only way
+       * to detect a missing provider was to call a real method and match its
+       * error message — which cost a full recursive workspace walk for a
+       * boolean, and could not distinguish "no provider" from a provider that
+       * failed transiently.
+       */
+      hasProvider?(): boolean;
+
       /**
        * Returns the full file tree for the current workspace root.
        */

package/types/punica.module.runtime.search.d.ts

@@ -48,12 +48,26 @@ declare module 'punica' {
       query(options: SearchQueryOptions): Promise<SearchResponse>;
 
       /**
-       * (Optional) Trigger a full or incremental index operation.
+       * (Optional) Trigger an index operation.
        * Implementations may ignore this if indexing is managed externally.
+       *
+       * Incremental by default — a host is expected to re-read only what
+       * changed since the last pass. `rebuild` asks for a from-scratch index,
+       * which a caller should only need after changing what gets indexed.
+       *
+       * `skipped` and `rebuilt` are optional so an older host stays conformant;
+       * a host that reports them makes "the index quietly grew to a gigabyte
+       * over a virtualenv" observable instead of invisible.
        */
       startIndex?(options?: {
         verbose?: boolean;
-      }): Promise<void | { addedOrUpdated: number; removed: number }>;
+        rebuild?: boolean;
+      }): Promise<void | {
+        addedOrUpdated: number;
+        removed: number;
+        skipped?: number;
+        rebuilt?: boolean;
+      }>;
     }
   }
 }

package/types/punica.module.shell.appBar.d.ts

@@ -0,0 +1,86 @@
+/**
+ * App bar type declarations.
+ *
+ * The app bar is the top strip of the window: branding on the left, the current
+ * workspace in the middle, actions on the right. On hosts that hide the native
+ * title bar it is also the window's drag handle, so it exists on every profile
+ * that lists `shell.appBar` — including the welcome layout, where it is the only
+ * way to move the window.
+ *
+ * Composition is declarative: a profile's `shell.appBar` spec describes the bar,
+ * and a shell renders it. Extensions may add their own actions at runtime
+ * through `punica.shell.AppBar.manager`, which is the same registry the profile
+ * items go through.
+ */
+
+declare module 'punica' {
+  export namespace shell {
+    namespace AppBar {
+      /** Which end of the bar an item belongs to. */
+      type AppBarAlignment = 'left' | 'right';
+
+      /** What the middle of the bar shows. */
+      type AppBarTitleMode = 'workspace' | 'product' | 'none';
+
+      /** One entry in an item's dropdown menu. */
+      interface AppBarMenuItem {
+        id: string;
+        label: string;
+        /** Command (or capability) id executed on select. */
+        command: string;
+        /** Draw a separator above this entry. */
+        separatorBefore?: boolean;
+      }
+
+      /**
+       * An action on the bar. `command` fires on click; `menu` opens a dropdown
+       * instead. An item may declare both, in which case the menu wins and the
+       * command is ignored.
+       */
+      interface AppBarItem {
+        id: string;
+        /** Icon markup (e.g. `<i class="fa-solid fa-gear"></i>`). */
+        icon?: string;
+        /** Optional text next to the icon. */
+        label?: string;
+        /** Tooltip / accessible name. */
+        title?: string;
+        alignment?: AppBarAlignment;
+        /**
+         * `'avatar'` draws a round account button whose glyph is the first
+         * letter of `label` (or the icon when there is none); `'action'` (the
+         * default) draws a flat icon button.
+         */
+        kind?: 'action' | 'avatar';
+        command?: string;
+        menu?: AppBarMenuItem[];
+        /**
+         * Command id returning a one-line summary rendered as the menu header
+         * (e.g. the licence state). Dropped when the command is not registered,
+         * which is how a host without the surface stays quiet.
+         */
+        summaryCommand?: string;
+      }
+
+      /** A profile's app bar composition (see `ProfileShellSpec.appBar`). */
+      interface AppBarSpec {
+        /** Bar height in px. Defaults to 38. */
+        height?: number;
+        /** What the centre region shows. Defaults to `'workspace'`. */
+        title?: AppBarTitleMode;
+        items?: AppBarItem[];
+      }
+
+      interface IAppBarManager {
+        /**
+         * Add (or replace) an item. Re-adding a known id keeps its original
+         * position, so an extension reload never reshuffles the bar.
+         */
+        addItem(item: AppBarItem): void;
+        removeItem(itemId: string): void;
+      }
+
+      const manager: IAppBarManager;
+    }
+  }
+}

package/types/punica.module.shell.profile.d.ts

@@ -21,6 +21,7 @@ declare module 'punica' {
        */
       type ShellModuleId =
         | 'shell.activityBar'
+        | 'shell.appBar'
         | 'shell.statusbar'
         | 'shell.view'
         | 'shell.views'
@@ -136,6 +137,13 @@ declare module 'punica' {
          * default minimal layout (single content slot).
          */
         layout?: ProfileLayoutSpec;
+        /**
+         * Optional app bar composition — branding, title mode and the actions
+         * on the top strip. Omitted means the profile has no app bar, even when
+         * `shell.appBar` is listed in `activeModules`, in which case the shell
+         * falls back to the module's own defaults.
+         */
+        appBar?: shell.AppBar.AppBarSpec;
         /**
          * Optional product defaults for the bottom panel. User settings
          * (Project > Global) override these; when both are unset the substrate