@punica/editor 1.6.0 → 1.6.2

package/package.json

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

package/types/index.d.ts

@@ -8,6 +8,7 @@
 /// <reference path="punica.module.shell.view.d.ts" />
 /// <reference path="punica.module.shell.views.d.ts" />
 /// <reference path="punica.module.shell.panelTabs.d.ts" />
+/// <reference path="punica.module.shell.panelLayout.d.ts" />
 /// <reference path="punica.module.shell.profile.d.ts" />
 /// <reference path="punica.module.shell.markdown.d.ts" />
 /// <reference path="punica.module.kernel.commands.d.ts" />

package/types/punica.module.extensions.api.d.ts

@@ -13,6 +13,15 @@ declare module 'punica' {
        * For activity bar items this will be invoked when the icon is clicked.
        */
       capability?: string;
+      /**
+       * Dock areas this view may be relocated to by the user (drag-drop /
+       * "Move to bottom / Move to right"). Only meaningful for `panel` and
+       * `secondarySidebar` views. When omitted, the substrate's default
+       * matrix already allows moving between `panel` and `secondarySidebar`,
+       * so most extensions never need to set this — declare it only to widen
+       * or restrict the default. Ignored by older cores.
+       */
+      relocatableTo?: Array<'panel' | 'secondarySidebar'>;
     }
 
     /**
@@ -57,6 +66,15 @@ declare module 'punica' {
          * panel view. Ignored by older cores.
          */
         toolbar?: PanelToolbarAction[];
+        /**
+         * When `false`, the tab is ON-DEMAND: no tab is added at load
+         * time. The placement is still registered, so the owning
+         * extension reveals the view (`context.ui.reveal`) when the
+         * relevant activity begins — reveal creates the tab — and hides
+         * it (`context.ui.hide`) when done, which removes the tab.
+         * Defaults to `true` (tab present at load). Ignored by older cores.
+         */
+        showOnStartup?: boolean;
       };
       activityBar?: Pick<BaseView, 'id' | 'name'> &
         Required<Pick<BaseView, 'title' | 'icon' | 'alignment'>>;

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

@@ -0,0 +1,84 @@
+/**
+ * Bottom-panel layout persistence (`punica.shell.PanelLayout`).
+ *
+ * The single store for user/product bottom-panel preferences that must
+ * survive restart: tab display mode, user-hidden tabs, user tab order, and
+ * per-view slot overrides (view relocation). It resolves a merged view of
+ * three tiers — **Project > Global > Profile default** — and exposes it via
+ * SYNCHRONOUS getters, because `PanelTabs.open()` and the views analysis
+ * decorator consult it as each tab/placement is created (which happens
+ * during extension load, after module `start()`).
+ *
+ * Persistence reuses `SettingsManager` under the `'system'` pseudo-extension
+ * (same precedent as `theme.profile`): global scope = the user's default
+ * across workspaces, project scope = a per-workspace override. Profile
+ * defaults come from the active `ApplicationProfile`
+ * (`shell.panel` / `shell.viewDefaults`).
+ */
+
+declare module 'punica' {
+  export namespace shell {
+    namespace PanelLayout {
+      /** How a panel tab renders its icon + label. */
+      type TabDisplayMode = 'icon' | 'label' | 'both';
+
+      /** Optional per-write scope + target-container selector. */
+      interface SetOptions {
+        /** When true, write to project (per-workspace) scope instead of global. */
+        workspace?: boolean;
+        /**
+         * Tabbed container the preference applies to. Defaults to `'panel'`
+         * (the bottom, horizontal strip), whose keys stay unscoped for
+         * backward compatibility; other slots (e.g. `'secondarySidebar'`,
+         * the right vertical strip) are stored under slot-scoped keys.
+         */
+        slot?: string;
+      }
+
+      interface IPanelLayoutManager {
+        /**
+         * Load settings (idempotent `settings.manager.load()`) and cache the
+         * merged Project > Global > Profile-default view in memory. Called by
+         * the module's `start()`; getters are synchronous afterwards.
+         */
+        load(): Promise<void>;
+
+        // ── Synchronous getters (consulted during tab/placement creation) ──
+        // Each takes the container `slot` (default `'panel'`): the bottom
+        // strip uses the legacy unscoped keys, other strips slot-scoped keys.
+        getDisplayMode(slot?: string): TabDisplayMode;
+        getHiddenTabs(slot?: string): string[];
+        isTabHidden(id: string, slot?: string): boolean;
+        /** User tab order (view ids, ascending), or undefined when unset. */
+        getTabOrder(slot?: string): string[] | undefined;
+        /** Persisted slot override for a view id, or undefined when none. */
+        getSlotOverride(viewId: string): string | undefined;
+
+        // ── Async setters (update cache immediately, then persist) ──
+        setDisplayMode(
+          mode: TabDisplayMode,
+          options?: SetOptions
+        ): Promise<void>;
+        setTabHidden(
+          id: string,
+          hidden: boolean,
+          options?: SetOptions
+        ): Promise<void>;
+        setTabOrder(ids: string[], options?: SetOptions): Promise<void>;
+        /**
+         * Record (or clear) a view→slot relocation. When `slot === homeSlot`
+         * the override is DELETED (reset-to-default) rather than stored as an
+         * identity mapping.
+         */
+        setSlotOverride(
+          viewId: string,
+          slot: string,
+          homeSlot: string,
+          options?: SetOptions
+        ): Promise<void>;
+      }
+
+      const manager: IPanelLayoutManager;
+    }
+  }
+}

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

@@ -39,7 +39,12 @@ declare module 'punica' {
         toolbar?: PanelToolbarAction[];
       }): void;
 
-      close(id: string): void;
+      /**
+       * Remove a tab from the strip. `silent: true` removes it without
+       * promoting a sibling to active — used when hiding an on-demand
+       * panel (the ViewRegistry collapses the slot separately).
+       */
+      close(id: string, options?: { silent?: boolean }): void;
       closeAll(): void;
 
       /** Returns the id of the currently active panel tab, or null. */
@@ -61,11 +66,77 @@ declare module 'punica' {
        * provider-rendered panel view is revealed.
        */
       activateTabVisual(id: string): void;
+
+      // ── Tab display / user layout (persisted via PanelLayout) ──
+
+      /**
+       * Set how every tab renders: `'icon'` (icon only), `'label'` (label
+       * only) or `'both'`. Applies to all current + future tabs and persists
+       * the choice. Re-runs the overflow recompute (widths change).
+       */
+      setDisplayMode(mode: 'icon' | 'label' | 'both'): void;
+      getDisplayMode(): 'icon' | 'label' | 'both';
+
+      /**
+       * User-hide a tab (distinct from overflow-collapse): the tab keeps its
+       * entry but is removed from the strip and the overflow menu until
+       * `showTab` restores it. Persisted. If the hidden tab was active, the
+       * first still-visible sibling is promoted.
+       */
+      hideTab(id: string): void;
+      showTab(id: string): void;
+
+      /**
+       * Apply a user-defined tab order (view ids ascending). Reorders the DOM,
+       * reindexes internal order, persists, and recomputes overflow.
+       */
+      setUserOrder(ids: string[]): void;
+
+      /**
+       * Enumerate current tabs in display order — used by the re-show menu and
+       * the Settings UI. `userHidden` reflects the user-hide state (not the
+       * transient overflow-collapse state).
+       */
+      listTabs(): Array<{ id: string; title: string; userHidden: boolean }>;
+    }
+
+    /**
+     * A tabbed dock container. The bottom panel renders a HORIZONTAL strip
+     * (icon+label), the right sidebar a VERTICAL strip (icon-only, activity-bar
+     * style). Both expose the same `PanelTabsApi`; only the tab-strip
+     * orientation and default display mode differ.
+     */
+    export type TabStripOrientation = 'horizontal' | 'vertical';
+
+    export interface TabbedContainerApi extends PanelTabsApi {
+      /** The layout slot this container renders into. */
+      readonly slotId: string;
+      /** Strip orientation (bottom = horizontal, right = vertical). */
+      readonly orientation: TabStripOrientation;
+    }
+
+    /**
+     * Registry addressing a tabbed container by slot. `moveView` and the
+     * views decorator use it to open/activate tabs on the container for a
+     * view's effective slot (bottom or right).
+     */
+    export interface PanelContainersApi {
+      /** The bottom (horizontal) container — same object as `PanelTabs`. */
+      readonly bottom: TabbedContainerApi;
+      /** The right (vertical) container. */
+      readonly right: TabbedContainerApi;
+      /** Container for a slot, or null for slots without a tabbed container. */
+      forSlot(slot: string): TabbedContainerApi | null;
     }
 
     /**
      * Global panel tabs API surfaced via `punica.shell.PanelTabs`.
+     * This is the bottom (horizontal) container; use `PanelContainers` to
+     * reach the right (vertical) one too.
      */
     export const PanelTabs: PanelTabsApi;
+
+    /** Slot → tabbed-container registry (`punica.shell.PanelContainers`). */
+    export const PanelContainers: PanelContainersApi;
   }
 }

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

@@ -28,6 +28,8 @@ declare module 'punica' {
         | 'shell.layout'
         | 'shell.contentTabs'
         | 'shell.panelTabs'
+        | 'shell.panelLayout'
+        | 'shell.viewDnd'
         | 'flow.shell'
         | (string & {});
 
@@ -134,6 +136,32 @@ declare module 'punica' {
          * default minimal layout (single content slot).
          */
         layout?: ProfileLayoutSpec;
+        /**
+         * Optional product defaults for the bottom panel. User settings
+         * (Project > Global) override these; when both are unset the substrate
+         * falls back to its own defaults (`tabDisplay: 'both'`, nothing hidden,
+         * manifest tab order). Non-enforced (read by `shell.panelLayout`).
+         */
+        panel?: ProfilePanelSpec;
+        /**
+         * Optional product defaults for view placement — e.g. a profile that
+         * ships the AI Assistant in the bottom panel instead of the right
+         * sidebar. `slotOverrides` maps a view id to its default slot; a user
+         * relocation (Project > Global) still wins. Non-enforced.
+         */
+        viewDefaults?: ProfileViewDefaultsSpec;
+      }
+
+      /** Product defaults for the bottom-panel tab strip (see ProfileShellSpec.panel). */
+      interface ProfilePanelSpec {
+        tabDisplay?: 'icon' | 'label' | 'both';
+        hiddenTabs?: string[];
+        tabOrder?: string[];
+      }
+
+      /** Product defaults for view→slot placement (see ProfileShellSpec.viewDefaults). */
+      interface ProfileViewDefaultsSpec {
+        slotOverrides?: Record<string, string>;
       }
 
       /**

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

@@ -42,6 +42,19 @@ declare module 'punica' {
          * the fleet migrates to view providers.
          */
         fallbackCommand?: string;
+        /**
+         * Dock areas this view may be relocated to (relocation primitive).
+         * Resolved by the analysis decorator from `slot` ∪ manifest
+         * `relocatableTo` ∪ the default `panel ↔ secondarySidebar` matrix.
+         * `moveView` validates its target against this set.
+         */
+        allowedSlots?: ViewSlotId[];
+        /**
+         * The manifest-declared slot — the view's "home". `slot` is the live
+         * (possibly user-overridden) location; moving back to `homeSlot`
+         * clears the persisted override (reset-to-default).
+         */
+        homeSlot?: ViewSlotId;
       }
 
       export interface ViewProviderDisposable {
@@ -129,6 +142,21 @@ declare module 'punica' {
          */
         hide(viewId: string, source: RevealSource): void;
 
+        /**
+         * Relocate a view to another dock area (relocation primitive).
+         * Validates `targetSlot ∈ placement.allowedSlots`, tears down the
+         * old slot's tab/host, moves the placement, persists the override
+         * via `PanelLayout.setSlotOverride`, and — if the view was visible —
+         * re-reveals it in the destination container (landing in that
+         * strip's orientation). Emits `shell.view.moved`. Publicly surfaced
+         * as the `shell.moveView` capability.
+         */
+        moveView(
+          viewId: string,
+          targetSlot: ViewSlotId,
+          source: RevealSource
+        ): Promise<void>;
+
         /**
          * Sync bookkeeping after the Layout manager wiped a slot's
          * hosts wholesale (primary sidebar switch resets the contextual