/**
 * THE LOOK POINTS — a workspace layout, a keymap and a style bundle as DATA a
 * package contributes (WORKBENCH.md §Contribution points: "Layouts, keymaps
 * and styles are DATA points: they need no code to load, which is what makes
 * a 'styled build' a manifest choice rather than a code change").
 *
 * A contribution module declares its point and exports ONE object:
 *
 *   `model.layout.ts`    export const point = 'workspace.layout';  export const layout: WorkspaceLayoutContribution
 *   `blender.keymap.ts`  export const point = 'workspace.keymap';  export const keymap: KeymapContribution
 *   `blender.style.ts`   export const point = 'workspace.style';   export const style: StyleContribution
 *
 * The editor registers what a project's declared packages contribute beside
 * its own built-ins — Look, Animate and Design as workspaces, the vgai keymap,
 * the Classic/Glass/Maya/Substance bundles — and never asks which package is
 * open: a build without the Blender look has no Model workspace.
 */
import type { WorkspaceArrangement } from './layout-arrangements.js';

/**
 * Every keyboard action the editor's chrome binds. A keymap binds these and
 * nothing else; a game never reads this table (play-mode input isolation is a
 * different mechanism).
 */
export type EditorKeyActionId =
  | 'edit.undo'
  | 'edit.redo'
  | 'edit.copy'
  | 'edit.cut'
  | 'edit.paste'
  | 'edit.duplicate'
  | 'edit.group'
  | 'edit.wrap'
  | 'edit.unwrap'
  | 'edit.selectAll'
  | 'edit.deselectAll'
  | 'edit.save'
  | 'edit.delete'
  | 'edit.enterScope'
  | 'edit.exitScopeOrDeselect'
  | 'edit.nudgeUp'
  | 'edit.nudgeUpCoarse'
  | 'edit.nudgeDown'
  | 'edit.nudgeDownCoarse'
  | 'edit.nudgeLeft'
  | 'edit.nudgeLeftCoarse'
  | 'edit.nudgeRight'
  | 'edit.nudgeRightCoarse'
  | 'view.resetPan'
  | 'view.commandPalette'
  | 'view.toggleConsole'
  | 'view.focusMode'
  | 'model.edit'
  | 'workspace.cycleNext'
  | 'workspace.cyclePrevious'
  | 'transform.combined'
  | 'transform.translate'
  | 'transform.rotate'
  | 'transform.scale'
  | 'viewport.toggleSnap'
  | 'viewport.frameSelection'
  | 'viewport.cyclePivot'
  | 'viewport.vertexSnapHold'
  | 'viewport.snapToFloor'
  | 'view.top'
  | 'view.front'
  | 'view.right'
  | 'view.perspective';

/**
 * One chord. `key` is matched case-insensitively against `KeyboardEvent.key`;
 * `code` (when set) is matched against `KeyboardEvent.code` instead, for
 * chords whose typed character varies by layout or modifier (Option+letter on
 * macOS types a symbol). `mod` is ⌘ on macOS and Ctrl elsewhere.
 */
export interface KeyChord {
  readonly key: string;
  readonly code?: string;
  readonly mod?: boolean;
  readonly shift?: boolean;
  readonly alt?: boolean;
}

/** The chords a keymap binds for the actions it names. An action a keymap
 *  omits keeps the editor's own binding; an EMPTY list unbinds it. */
export type KeymapBindings = Partial<Record<EditorKeyActionId, readonly KeyChord[]>>;

export interface KeymapContribution {
  /** The `keymap` settings value that selects it. */
  readonly id: string;
  readonly title: string;
  readonly description: string;
  readonly bindings: KeymapBindings;
}

export type WorkspaceLayoutRegions = NonNullable<WorkspaceArrangement['regions']>;

export interface WorkspaceLayoutContribution {
  readonly id: string;
  readonly title: string;
  readonly description: string;
  /** What the workspace needs the project to DECLARE before it applies:
   *  `'mounts'` (at least one root that plays) or a document kind the
   *  project's table lists. Omitted: every project. */
  readonly requires?: 'mounts' | { readonly documentKind: string };
  /** Which chrome regions the workspace shows; absent means every region. */
  readonly regions?: WorkspaceLayoutRegions;
  /** The dock's shipped arrangement for this workspace — captured Dockview
   *  geometry (`capturedWorkspaceLayouts` carries the ones the editor
   *  shipped). Absent: the dock's standing arrangement, as Game uses. */
  readonly state?: WorkspaceArrangement['state'];
}

export interface StyleContribution {
  readonly id: string;
  readonly title: string;
  /** A palette id the editor knows — a built-in, or the `palette` document
   *  this contribution carries. */
  readonly paletteId: string;
  readonly materialId: 'classic' | 'glass';
  readonly composition: 'docked' | 'floating';
  /** Region defaults beneath each workspace's own. */
  readonly regions?: WorkspaceLayoutRegions;
  /** A v3 palette DOCUMENT (the same shape a person imports), registered into
   *  the editor's theme library with this bundle. */
  readonly palette?: unknown;
}