@punica/editor 1.0.6 → 1.0.8

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

@@ -0,0 +1,87 @@
+declare module 'punica' {
+  export namespace shell {
+    /**
+     * Punica Components
+     * Type definitions for punica-components web elements
+     */
+    export namespace Components {
+      // Punica element tag names from punica-components
+      // This list matches punica-components/src/component.d.ts
+      // Maintained manually to avoid React/JSX dependencies
+      export type Element =
+        | 'punica-accordion'
+        | 'punica-accordion-summary'
+        | 'punica-accordion-details'
+        | 'punica-select'
+        | 'punica-select-item'
+        | 'punica-popover'
+        | 'punica-qr-code'
+        | 'punica-pagination'
+        | 'punica-button'
+        | 'punica-button-group'
+        | 'punica-icon-button'
+        | 'punica-avatar'
+        | 'punica-alert'
+        | 'punica-alert-action'
+        | 'punica-alert-icon'
+        | 'punica-alert-content'
+        | 'punica-app-bar'
+        | 'punica-badge'
+        | 'punica-chip'
+        | 'punica-input'
+        | 'punica-textarea'
+        | 'punica-container'
+        | 'punica-hidden'
+        | 'punica-icon'
+        | 'punica-date-picker'
+        | 'punica-drawer'
+        | 'punica-paper'
+        | 'punica-split-button'
+        | 'punica-card'
+        | 'punica-card-header'
+        | 'punica-card-media'
+        | 'punica-card-content'
+        | 'punica-card-actions'
+        | 'punica-box'
+        | 'punica-tooltip'
+        | 'punica-divider'
+        | 'punica-switch'
+        | 'punica-modal'
+        | 'punica-modal-header'
+        | 'punica-modal-content'
+        | 'punica-modal-footer'
+        | 'punica-dialog'
+        | 'punica-dialog-header'
+        | 'punica-dialog-content'
+        | 'punica-dialog-footer'
+        | 'punica-skeleton'
+        | 'punica-checkbox'
+        | 'punica-menu'
+        | 'punica-menu-item'
+        | 'punica-tab'
+        | 'punica-tab-item'
+        | 'punica-tab-panel'
+        | 'punica-list-view'
+        | 'punica-list-view-item'
+        | 'punica-single-select-list'
+        | 'punica-single-select-list-item'
+        | 'punica-multi-select-list'
+        | 'punica-multi-select-list-item'
+        | 'punica-time-picker'
+        | 'punica-typography'
+        | 'punica-toggle-button'
+        | 'punica-toggle-button-group'
+        | 'punica-context-menu'
+        | 'punica-context-menu-item'
+        | 'punica-context-menu-sperator'
+        | 'punica-toolbar'
+        | 'punica-toast'
+        | 'punica-toaster'
+        | 'punica-progress-line'
+        | 'punica-virtual-list'
+        | 'punica-virtual-table'
+        | 'punica-col'
+        | 'punica-row';
+    }
+  }
+}

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

@@ -0,0 +1,33 @@
+declare module 'punica' {
+  export namespace shell {
+    /**
+     * Content tab management capability for the main editor area.
+     */
+    export interface ContentTabsApi {
+      open(options: {
+        path: string;
+        title?: string;
+        viewType?: string;
+      }): HTMLElement | null;
+      close(path: string): void;
+      closeOthers(path: string): void;
+      closeAll(): void;
+      setDirty(path: string, dirty: boolean): void;
+      /**
+       * Returns the path of the currently active content tab, or null if none.
+       */
+      getActivePath(): string | null;
+      /**
+       * Returns the viewType of the currently active content tab, or null if none.
+       * View types are provided by content extensions when opening tabs
+       * (e.g. "code", "flow-book", "markdown").
+       */
+      getActiveViewType(): string | null;
+    }
+
+    /**
+     * Global content tabs API surfaced via `punica.shell.ContentTabs`.
+     */
+    export const ContentTabs: ContentTabsApi;
+  }
+}

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

@@ -0,0 +1,25 @@
+declare module 'punica' {
+  export namespace shell {
+    export namespace DragDrop {
+      type DragDropEvents = 'dragging' | 'dragStart' | 'dragStop';
+      type Events = { [key in DragDropEvents]: string };
+      type Point = {
+        x: number;
+        y: number;
+      };
+      type PositionDetail = {
+        offsetX: number;
+        offsetY: number;
+        pageX: number;
+        pageY: number;
+        clientX: number;
+        clientY: number;
+      };
+      interface IServiceDragDrop {
+        handleDragStart(event: MouseEvent): void;
+        handleDragging(event: MouseEvent): void;
+        handleDragStop(event: MouseEvent): void;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+declare module 'punica' {
+  export namespace shell {
+    export namespace KeyboardShortcuts {
+      interface IDisposable {
+        dispose(): void;
+      }
+
+      interface IKey {
+        key: string;
+        ctrlKey?: boolean;
+        shiftKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+      }
+
+      interface IShortcut {
+        command: string;
+        keys: IKey[];
+        disposable?: IDisposable;
+        /**
+         * Optional context expression that determines when the shortcut is active.
+         * The first supported context key is:
+         *   - view: the current active content tab viewType (e.g. "code", "flow-book").
+         * Example: "view == code", "view == flow-book".
+         */
+        when?: string;
+      }
+
+      interface IShortcutManager {
+        registerShortcut(shortcut: IShortcut): void;
+        unregisterShortcut(keys: IKey[]): void;
+        handleKeyEvent(event: KeyboardEvent): void;
+      }
+
+      export const manager: IShortcutManager;
+    }
+  }
+}

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

@@ -0,0 +1,106 @@
+declare module 'punica' {
+  export namespace shell {
+    export namespace Layout {
+      export type LayoutSlotId = string;
+
+      export type LayoutSlotRole =
+        | 'content'
+        | 'primarySidebar'
+        | 'secondarySidebar'
+        | 'panel'
+        | 'statusbar'
+        | 'activityBar'
+        | 'overlay'
+        | 'custom';
+
+      export interface LayoutSlot {
+        id: LayoutSlotId;
+        role?: LayoutSlotRole;
+        content: HTMLElement;
+      }
+
+      export type LayoutNode =
+        | { type: 'row'; sizes?: number[]; children: LayoutNode[] }
+        | { type: 'column'; sizes?: number[]; children: LayoutNode[] }
+        | { type: 'slot'; id: LayoutSlotId; role?: LayoutSlotRole };
+
+      export interface LayoutProfile {
+        id: string;
+        title: string;
+        root: LayoutNode;
+      }
+
+      export interface ILayoutManager {
+        /**
+         * Render the current layout profile into the given container.
+         */
+        render(container: HTMLElement): void;
+
+        /**
+         * Apply a new layout profile, rebuilding the DOM and slot map.
+         * Backward-compatible API — use `applyApplicationProfile` for
+         * profile-driven structural slot derivation.
+         */
+        applyProfile(profile: LayoutProfile): void;
+
+        /**
+         * Apply an ApplicationProfile's shell spec to the layout.
+         * Derives structural slots from `profile.shell.activeModules`
+         * rather than relying on hardcoded profile id checks.
+         * Called by ProfileManager during bootstrap.
+         */
+        applyApplicationProfile(
+          profile: shell.Profile.ApplicationProfile
+        ): void;
+
+        /**
+         * Get the currently active layout profile.
+         */
+        getActiveProfile(): LayoutProfile;
+
+        /**
+         * Get a slot by id. Returns undefined if the slot is not present
+         * in the active layout profile.
+         */
+        getSlot(id: LayoutSlotId): LayoutSlot | undefined;
+
+        /**
+         * Create (or re-attach) the DOM host for a view WITHOUT any
+         * visibility side effect. New hosts start hidden. Visibility is
+         * changed only by the shell ViewRegistry
+         * (`punica.shell.Views.manager.reveal`, i.e. the
+         * `shell.revealView` capability).
+         */
+        materializeViewHost(slotId: LayoutSlotId, viewId: string): HTMLElement;
+
+        /**
+         * Make a materialized view the visible one in its slot.
+         * Visibility authority: only the shell ViewRegistry and the
+         * legacy `ensureViewHost` compatibility path call this — do not
+         * call it from extensions.
+         */
+        showView(slotId: LayoutSlotId, viewId: string): void;
+
+        /** Hide every view host in a slot. */
+        hideSlotViews(slotId: LayoutSlotId): void;
+
+        /** Remove a view host from the DOM (extension deactivation). */
+        removeViewHost(slotId: LayoutSlotId, viewId: string): void;
+
+        /**
+         * LEGACY compatibility surface — materialize + reveal in one
+         * call. During a headless extension activation the reveal half
+         * is blocked (host is created hidden and a
+         * `shell.view.revealBlocked` event is emitted).
+         *
+         * @deprecated Register a ViewProvider
+         * (`context.ui.registerViewProvider`) and reveal via the
+         * `shell.revealView` capability instead.
+         */
+        ensureViewHost(slotId: LayoutSlotId, viewId: string): HTMLElement;
+      }
+
+      export const manager: ILayoutManager;
+    }
+  }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Shared Markdown renderer type declarations — `punica.shell.Markdown`.
+ *
+ * The substrate-central markdown→HTML renderer (markdown-it + highlight.js)
+ * consumed by every UI surface so code blocks and typography are identical
+ * everywhere. Pure data / DOM-free (D1): `render` returns an HTML string and
+ * `css` is a stylesheet string.
+ *
+ * Naming convention mirrors other shell module type files:
+ * `punica.module.shell.<area>.d.ts`.
+ */
+
+declare module 'punica' {
+  export namespace shell {
+    namespace Markdown {
+      interface RenderOptions {
+        /**
+         * Syntax-highlight fenced code blocks (default true). Pass false for
+         * per-token streaming — highlighting is applied once the block is
+         * finalized (avoids re-highlighting partial code every token).
+         */
+        highlight?: boolean;
+      }
+
+      /** Render a Markdown string to a safe, DOM-free HTML fragment. */
+      function render(src: string, opts?: RenderOptions): string;
+
+      /**
+       * Stylesheet for the rendered HTML (hljs One Dark palette + code-block
+       * chrome hooks + markdown typography). Inject once per document via
+       * `punica.extensions.Styles.register('punica:markdown', css, …)`.
+       */
+      const css: string;
+    }
+  }
+}

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

@@ -0,0 +1,71 @@
+declare module 'punica' {
+  export namespace shell {
+    /**
+     * A single icon-button action shown in the panel tab bar's toolbar
+     * area while the owning view is the active panel view. Clicking the
+     * button dispatches `command` through
+     * `punica.kernel.Commands.manager.executeCommand` (the single command
+     * choke point — lazy-activates the owning extension when needed).
+     */
+    export interface PanelToolbarAction {
+      /** Unique within the owning view. */
+      id: string;
+      /** Tooltip / aria-label. */
+      title: string;
+      /** Raw HTML icon markup, e.g. '<i class="fa-solid fa-plus"></i>'. */
+      icon?: string;
+      /** Command id dispatched on click. */
+      command: string;
+    }
+
+    /**
+     * Panel tab management for the bottom panel area (problems, terminals, etc.).
+     */
+    export interface PanelTabsApi {
+      open(options: {
+        id: string;
+        title: string;
+        commandId: string;
+        iconClass?: string;
+        order?: number;
+        /**
+         * When false, the panel tab is added but not activated.
+         */
+        autoActivate?: boolean;
+        /**
+         * Toolbar actions rendered in the tab bar's right-side toolbar
+         * area, visible only while this view is the active panel view.
+         */
+        toolbar?: PanelToolbarAction[];
+      }): void;
+
+      close(id: string): void;
+      closeAll(): void;
+
+      /** Returns the id of the currently active panel tab, or null. */
+      getActiveId(): string | null;
+
+      /**
+       * Activate a tab and execute its bound command (legacy render
+       * path). Blocked during headless extension activation — a
+       * capability call must never steal the visible panel; reveal via
+       * the `shell.revealView` capability instead.
+       *
+       * @param id
+       */
+      setActive(id: string): void;
+
+      /**
+       * Update the tab strip visual selection WITHOUT executing the
+       * tab's command. Used by the shell ViewRegistry when a
+       * provider-rendered panel view is revealed.
+       */
+      activateTabVisual(id: string): void;
+    }
+
+    /**
+     * Global panel tabs API surfaced via `punica.shell.PanelTabs`.
+     */
+    export const PanelTabs: PanelTabsApi;
+  }
+}

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

@@ -0,0 +1,278 @@
+/**
+ * ApplicationProfile type declarations.
+ *
+ * Minimum viable v1 schema: 4 enforced dimensions
+ * (identity, shell, theme, capabilities) + 6 optional
+ * non-enforced dimensions for future progressive enforcement.
+ *
+ * Naming convention mirrors other shell module type files:
+ * `punica.module.shell.<area>.d.ts`.
+ */
+
+declare module 'punica' {
+  export namespace shell {
+    namespace Profile {
+      /**
+       * Shell module identifiers that can be activated per-profile.
+       * These map directly to MODULE_NAMES entries in identifiers.ts.
+       */
+      type ShellModuleId =
+        | 'shell.activityBar'
+        | 'shell.statusbar'
+        | 'shell.view'
+        | 'shell.views'
+        | 'shell.keyboardShortcuts'
+        | 'shell.layout'
+        | 'shell.contentTabs'
+        | 'shell.panelTabs'
+        | 'flow.shell';
+
+      /**
+       * Per-profile branding overrides.
+       * All fields are optional — omitted fields fall back to substrate defaults.
+       */
+      interface ProfileBranding {
+        /** URL or data URI for the product logo. */
+        logo?: string;
+        /** URL for the browser-tab favicon. */
+        favicon?: string;
+        /** Product display name shown in title bars and "about" dialogs. */
+        productName?: string;
+        /** Raw CSS injected into the document for profile-specific overrides. */
+        customCss?: string;
+      }
+
+      /**
+       * v1 enforced: theme presentation.
+       */
+      interface ProfileThemeSpec {
+        /** Color scheme preference. */
+        mode: 'light' | 'dark' | 'auto';
+        /** Layout density — defaults to 'comfortable'. */
+        density?: 'compact' | 'comfortable';
+        /**
+         * CSS variable overrides. Keys are CSS custom property names
+         * (without leading `--`); the ProfileManager prepends `--punica-`.
+         */
+        colors?: Record<string, string>;
+        branding?: ProfileBranding;
+      }
+
+      /** Capability origin categories from the unified registry. */
+      type CapabilityOrigin =
+        | 'core'
+        | 'extension'
+        | 'instruction-class'
+        | 'ivy-node'
+        | 'ivy-agent'
+        | 'mcp';
+
+      /**
+       * v1 enforced: per-profile capability budget.
+       *
+       * Enforcement order (gateway profileBudget middleware):
+       * 1. `allowedOrigins` — reject if origin not listed (skipped when omitted)
+       * 2. `deniedIds` — explicit blocklist (takes precedence over allowedIds)
+       * 3. `allowedIds` — `'*'` = allow all; array = allowlist
+       */
+      interface ProfileCapabilityBudget {
+        /**
+         * `'*'` = allow all capability ids (default permissive).
+         * Array = allowlist — only these ids may be invoked.
+         */
+        allowedIds: string[] | '*';
+        /**
+         * Explicit blocklist. These ids are rejected even when present
+         * in `allowedIds`. Evaluated before the allowlist check.
+         */
+        deniedIds?: string[];
+        /**
+         * Filter by capability origin. When provided, only capabilities
+         * from listed origins are allowed. Evaluated first (cheapest check).
+         * Trinity invariant: all 4 origins treated equally.
+         */
+        allowedOrigins?: CapabilityOrigin[];
+      }
+
+      /** Layout sub-spec embedded in the profile's shell spec. */
+      interface ProfileLayoutSpec {
+        /**
+         * Layout identifier — used as the `data-profile-id` attribute and
+         * for host CSS. Must be unique within a host's profile set.
+         */
+        id: string;
+        /**
+         * Root layout tree (same as `shell.Layout.LayoutNode`).
+         * Substrate renders this as a recursive split tree inside the main
+         * content area.
+         */
+        root: shell.Layout.LayoutNode;
+      }
+
+      /**
+       * v1 enforced: shell composition spec.
+       */
+      interface ProfileShellSpec {
+        /**
+         * Shell modules to bootstrap for this profile.
+         * Only modules listed here are registered in the ModuleRegistry
+         * during bootstrap. Kernel and runtime modules are always registered
+         * unconditionally.
+         *
+         * Structural DOM slots are derived from this list:
+         * - `shell.activityBar` → creates `activityBar` slot
+         * - `shell.view` → creates `primarySidebar` + `contentSidebar` slots
+         * - `shell.statusbar` → creates `statusbar` slot
+         */
+        activeModules: ShellModuleId[];
+        /**
+         * Optional layout tree. When omitted, the ProfileManager applies the
+         * default minimal layout (single content slot).
+         */
+        layout?: ProfileLayoutSpec;
+      }
+
+      /**
+       * v1 enforced: profile identity.
+       */
+      interface ProfileIdentity {
+        /**
+         * Stable machine-readable profile id.
+         * Examples: `'ivyx-classic'`, `'agent-ops-console'`.
+         */
+        id: string;
+        /** Human-readable product/profile name. */
+        name: string;
+        /**
+         * Semver profile version. Substrate uses this for profile schema
+         * migration (future migration registry — same pattern as flow authoring).
+         */
+        version: string;
+        /**
+         * Target audience descriptor.
+         * Examples: `'ml-engineer'`, `'compliance-officer'`, `'end-user'`.
+         */
+        audience?: string;
+        branding?: ProfileBranding;
+      }
+
+      // ─── Optional v1 non-enforced dimensions ────────────────────────────────
+      // Declared as types so hosts can populate them; the substrate runtime
+      // does not validate or enforce these in v1.
+
+      interface ProfileExtensionsSpec {
+        defaultInstalled?: string[];
+        allowedToInstall?: string[] | '*';
+      }
+
+      interface ProfileCommandPaletteSpec {
+        visibleCommands?: string[];
+        hiddenCommands?: string[];
+      }
+
+      interface ProfileAuthoringSpec {
+        mode?: 'admin' | 'end-user' | 'ai';
+      }
+
+      interface ProfileRedactionRule {
+        field: string;
+        strategy: 'redact' | 'hash' | 'drop';
+      }
+
+      interface ProfileTelemetrySpec {
+        capture?: boolean;
+        redactionRules?: ProfileRedactionRule[];
+      }
+
+      interface ProfileLocalizationSpec {
+        default?: string;
+        supported?: string[];
+      }
+
+      interface ProfileTenancySpec {
+        multiTenant?: boolean;
+      }
+
+      /**
+       * ApplicationProfile — the substrate's product-agnosticity contract.
+       *
+       * A single binary ships multiple products by swapping this profile.
+       * `ivyx-classic` and `agent-ops-console` are the two proof profiles
+       * that demonstrate the "two products, one substrate" claim (ApplicationProfile).
+       *
+       * Schema version: `'1'` (enforces 4 dimensions).
+       */
+      interface ApplicationProfile {
+        /** Schema version — required for future migration registry. */
+        schemaVersion: '1';
+
+        // ── v1 enforced dimensions ──────────────────────────────────────────
+        identity: ProfileIdentity;
+        shell: ProfileShellSpec;
+        theme: ProfileThemeSpec;
+        capabilities: ProfileCapabilityBudget;
+
+        // ── v1 optional dimensions (shape declared, not enforced at runtime) ─
+        extensions?: ProfileExtensionsSpec;
+        commandPalette?: ProfileCommandPaletteSpec;
+        authoring?: ProfileAuthoringSpec;
+        telemetry?: ProfileTelemetrySpec;
+        localization?: ProfileLocalizationSpec;
+        tenancy?: ProfileTenancySpec;
+      }
+
+      /** Result returned by `switchProfile()` — always reload-based in v1. */
+      type ProfileSwitchResult = { reloadRequired: true };
+
+      /**
+       * ProfileRegistry — registers and retrieves ApplicationProfiles.
+       */
+      interface IProfileRegistry {
+        /**
+         * Register a profile. Throws if a profile with the same id is already
+         * registered (use `replace` option in future v2 to override).
+         */
+        register(profile: ApplicationProfile): void;
+        /** Get a profile by id. Returns undefined if not registered. */
+        get(id: string): ApplicationProfile | undefined;
+        /** Get the currently active profile. */
+        getActive(): ApplicationProfile;
+        /**
+         * Signal profile switch. Always returns `{ reloadRequired: true }` in
+         * v1 — the substrate does not teardown/re-bootstrap modules in-memory.
+         * The host is responsible for triggering a full reload.
+         */
+        switchProfile(id: string): ProfileSwitchResult;
+      }
+
+      /** Loader options for `ProfileLoader.load()`. */
+      type ProfileSource =
+        | { kind: 'inline'; profile: ApplicationProfile }
+        | { kind: 'json'; json: string }
+        | { kind: 'object'; data: unknown };
+
+      /** Validates an ApplicationProfile against the v1 schema. */
+      interface IProfileValidator {
+        validate(
+          data: unknown
+        ):
+          | { valid: true; profile: ApplicationProfile }
+          | { valid: false; errors: string[] };
+      }
+
+      /** Top-level manager surface exposed as `punica.shell.Profile.manager`. */
+      interface IProfileManager {
+        readonly registry: IProfileRegistry;
+        readonly validator: IProfileValidator;
+        /**
+         * Load and activate a profile from a source.
+         * Must be called before `moduleRegistry.bootstrapAll()`.
+         */
+        loadProfile(source: ProfileSource | ApplicationProfile | string): void;
+      }
+
+      // Namespace shape for punica.shell.Profile
+      const manager: IProfileManager;
+    }
+  }
+}