@punica/editor 1.5.0 → 1.6.0

package/package.json

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

package/types/index.d.ts

@@ -132,4 +132,135 @@ export function bootstrap(options?: {
  */
 export function start(): Promise<void>;
 
+// ---------------------------------------------------------------------------
+// Headless seam + substrate re-exports.
+//
+// These are the `@punica/editor` package's runtime exports consumed by an
+// external shell package (`@punica/editor-shell-classic`) built as its own
+// bundle with `@punica/editor` marked external. The corresponding runtime
+// values live in `src/index.ts` (re-exported from `src/impl/core/*`).
+
+/** Module lifecycle states (mirrors `core/moduleTypes.ts`). */
+export enum ModuleLifecycleState {
+  CREATED = 'created',
+  BOOTSTRAPPING = 'bootstrapping',
+  BOOTSTRAPPED = 'bootstrapped',
+  BOOTSTRAP_FAILED = 'bootstrap_failed',
+  STARTING = 'starting',
+  STARTED = 'started',
+  START_FAILED = 'start_failed',
+  READY = 'ready'
+}
+
+/** Module registry surface reachable from a module's lifecycle context. */
+export interface IModuleRegistry {
+  register(module: IModule): void;
+  get(name: string): IModule | undefined;
+  getAll(): readonly IModule[];
+  resolveBootstrapOrder(): string[];
+  resolveStartOrder(): string[];
+  bootstrapAll(): Promise<void>;
+  startAll(): Promise<void>;
+  getState(moduleName: string): ModuleLifecycleState | undefined;
+  areAllModulesReady(): boolean;
+  detectPreBootstrapAccess(): string[];
+}
+
+/** Context passed to module lifecycle methods. */
+export interface ModuleContext {
+  readonly phase: 'bootstrap' | 'start';
+  readonly punica: typeof import('punica');
+  readonly registry: IModuleRegistry;
+}
+
+/** Core module interface all Punica modules implement. */
+export interface IModule {
+  readonly name: string;
+  readonly version: string;
+  readonly dependencies: readonly string[];
+  readonly state: ModuleLifecycleState;
+  bootstrap(context: ModuleContext): Promise<void>;
+  start(context: ModuleContext): Promise<void>;
+}
+
+/** A shell contribution registered via `registerShell()`. */
+export interface ShellContribution {
+  facade?: Record<string, unknown>;
+  moduleFactories?: Record<string, () => IModule>;
+  profiles?: import('punica').shell.Profile.ApplicationProfile[];
+  defaultProfileId?: string;
+}
+
+/**
+ * Register a shell contribution (facade, profile-gated modules, profiles).
+ * Call after `initialize()` and before `bootstrap()`. Multiple calls
+ * accumulate.
+ */
+export function registerShell(contribution: ShellContribution): void;
+
+/** Centralized module-name constants (`MODULE_NAMES.SHELL.LAYOUT`, …). */
+export const MODULE_NAMES: {
+  readonly [group: string]: { readonly [key: string]: string };
+};
+
+/** Centralized command-id constants (`COMMAND_IDS.WORKFLOW.RUN_START`, …). */
+export const COMMAND_IDS: {
+  readonly [group: string]: { readonly [key: string]: string };
+};
+
+/** True when running on a Mac platform (affects key-chord parsing). */
+export function isMacPlatform(): boolean;
+
+/** Parse a `'mod+shift+p'`-style chord into an `IKey`. */
+export function parseKeyChord(
+  chord: string,
+  isMac?: boolean
+): import('punica').shell.KeyboardShortcuts.IKey;
+
+/** True while executing inside a headless UI-activation scope. */
+export function isHeadlessScope(): boolean;
+
+/** Enter a headless UI-activation scope (view reveals materialize hidden). */
+export function enterHeadlessScope(): void;
+
+/** Exit the current headless UI-activation scope. */
+export function exitHeadlessScope(): void;
+
+/** Run `fn` inside a headless UI-activation scope, restoring the prior scope. */
+export function runInHeadlessScope<T>(fn: () => Promise<T>): Promise<T>;
+
+/** Options for `emitShellEvent()`. */
+export interface ShellEventOptions {
+  name: string;
+  source?: string;
+  correlationId?: string;
+  traceId?: string;
+  kind?: 'info' | 'warn' | 'error';
+  payload: Record<string, unknown>;
+}
+
+/** Best-effort kernel-event emit from the shell/profile layer. */
+export function emitShellEvent(opts: ShellEventOptions): boolean;
+
+/** The core-owned ApplicationProfile mechanism (`punica.shell.Profile`). */
+export const Profile: {
+  readonly manager: import('punica').shell.Profile.IProfileManager;
+};
+
+/** ApplicationProfile validator interface (host-injectable). */
+export interface IProfileValidator {
+  validate(data: unknown):
+    | {
+        valid: true;
+        profile: import('punica').shell.Profile.ApplicationProfile;
+      }
+    | { valid: false; errors: string[] };
+}
+
+/** Returns the injected validator if set, else the minimal default. */
+export function getProfileValidator(): IProfileValidator;
+
+/** Inject a production-grade (e.g. Ajv-backed) profile validator. */
+export function setProfileValidator(v: IProfileValidator): void;
+
 export {};