@volter/editor-sdk 0.5.57

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Volter AI, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+Copyright 2026 Volter AI, Inc.
+
+Project tool registry, provider execution and related types were transferred
+from the Apache-2.0 @vgai/sdk package. Original source hashes and revision are
+recorded in provenance/editor-server.json.
+
+The project output-root policy is Apache-2.0, transferred from the original
+SDK; its exact source is recorded in provenance/editor-server.json.

package/README.md

@@ -0,0 +1,19 @@
+# Editor SDK
+
+Extension, contribution and editor-session APIs for Volter Editor. This package
+depends on the project contracts, not the editor implementation or game runtime.
+
+The viewport presentation contract accepts a root identity and native mounted
+adapter surface. It does not require a game's input system, loop or execution
+API. Richer product-owned roots can satisfy that interface directly.
+
+Account/generation projections, project-tool declarations and tab observations
+used by this SDK live here, transferred from the former general SDK. They are
+data contracts, not provider integrations. The rest of that old SDK is not
+included by default. Editor appearance data types have one owner in the project
+contract and are exposed through the SDK's contribution-facing entry points.
+
+Run `npm run typecheck -w @volter/editor-sdk` through the active World. This
+package is private during migration. Existing session wire names remain intact
+until their host and Code-OSS consumers move together; package renaming alone
+does not complete product branding or consumer cutover.

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@volter/editor-sdk",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.5.57",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Extension, contribution and session APIs for Volter Editor.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/editor-sdk"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./contributions": "./src/contributions.ts",
+    "./document-probe": "./src/document-probe.ts",
+    "./extension": "./src/extension.ts",
+    "./share": "./src/share.ts",
+    "./session": "./src/session.ts",
+    "./session/*": "./src/session/*.ts",
+    "./layouts": "./src/layouts.tsx",
+    "./layout-arrangements": "./src/layout-arrangements.ts",
+    "./host": "./src/host.ts",
+    "./looks": "./src/looks.ts",
+    "./widgets": "./src/widgets/index.ts",
+    "./commands": "./src/commands.ts",
+    "./chrome": "./src/chrome.ts",
+    "./views": "./src/views.ts",
+    "./services": "./src/services.ts",
+    "./account": "./src/account.ts",
+    "./generations": "./src/generations.ts",
+    "./project-tool-catalog": "./src/project-tool-catalog.ts",
+    "./tab-census": "./src/project/tab-census.ts",
+    "./selection": "./src/selection.tsx",
+    "./client": "./src/client.ts",
+    "./session/product-locator": "./src/session/product-locator.ts",
+    "./session/editor-compatibility": "./src/session/editor-compatibility.ts",
+    "./session/relative-path-guard": "./src/session/relative-path-guard.ts",
+    "./session/workbench-locator": "./src/session/workbench-locator.ts",
+    "./session/tool-contribution-convention": "./src/session/tool-contribution-convention.ts",
+    "./session/command-table": "./src/session/command-table.ts",
+    "./session/collaboration-types": "./src/session/collaboration-types.ts",
+    "./tools/provider-execution": "./src/tools/provider-execution.ts",
+    "./index": "./src/index.ts",
+    "./session/build-report": "./src/session/build-report.ts",
+    "./session/editor-control-lifecycle": "./src/session/editor-control-lifecycle.ts",
+    "./session/editor-control-protocol": "./src/session/editor-control-protocol.ts",
+    "./session/source-glob": "./src/session/source-glob.ts",
+    "./project/tab-census": "./src/project/tab-census.ts",
+    "./tools/registry": "./src/tools/registry.ts",
+    "./session/game-css-scope": "./src/session/game-css-scope.ts",
+    "./session/entrypoint-selection-source": "./src/session/entrypoint-selection-source.ts",
+    "./tools/types": "./src/tools/types.ts",
+    "./session/editor-brand": "./src/session/editor-brand.ts",
+    "./tools/errors": "./src/tools/errors.ts",
+    "./project/output-roots": "./src/project/output-roots.ts"
+  },
+  "dependencies": {
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0",
+    "@fortawesome/react-fontawesome": "^3.2.0",
+    "@types/three": "^0.180.0",
+    "typescript": "^5.6.0",
+    "undici": "^7.28.0",
+    "zod": "^4.3.6",
+    "@volter/editor-project": "0.5.57",
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": "^0.180.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "imports": {
+    "#http-transport": {
+      "browser": "./src/http-transport.browser.ts",
+      "default": "./src/http-transport.node.ts"
+    }
+  }
+}

package/src/account.ts

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+
+// Account identity and billing preference are host configuration, never generation-call inputs.
+export const AccountBackendSchema = z.enum(['mock', 'live']);
+export const AccountPlanSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  status: z.enum(['free', 'trialing', 'active', 'past_due', 'cancelling']),
+  interval: z.enum(['month', 'year']).optional(),
+  renewsAt: z.string().datetime().optional(),
+  endsAt: z.string().datetime().optional(),
+});
+export const AccountCreditsSchema = z.object({
+  included: z.number().nonnegative(),
+  purchased: z.number().nonnegative(),
+  used: z.number().nonnegative(),
+  reserved: z.number().nonnegative(),
+  remaining: z.number().nonnegative(),
+  resetsAt: z.string().datetime().optional(),
+  purchasedExpiresAt: z.string().datetime().optional(),
+});
+export const AccountSpendPolicySchema = z.object({
+  overageEnabled: z.boolean(),
+  monthlyLimitCredits: z.number().nonnegative(),
+  alertThresholds: z.array(z.number().min(1).max(100)).max(8),
+  autoReload: z
+    .object({
+      enabled: z.boolean(),
+      whenRemainingBelow: z.number().nonnegative(),
+      reloadTo: z.number().positive(),
+      monthlyLimitCredits: z.number().nonnegative(),
+    })
+    .optional(),
+});
+export const AccountAlertSchema = z.object({
+  id: z.string().min(1),
+  kind: z.enum(['threshold', 'auto_reload_succeeded', 'auto_reload_failed']),
+  message: z.string().min(1),
+  createdAt: z.string().datetime(),
+  readAt: z.string().datetime().optional(),
+});
+export const AccountUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.string().email(),
+  name: z.string().min(1).optional(),
+});
+export const AccountOrganizationDomainSchema = z.object({
+  name: z.string().min(1),
+  verified: z.boolean(),
+  enrollmentMode: z.enum([
+    'manual_invitation',
+    'automatic_invitation',
+    'automatic_suggestion',
+    'enterprise_sso',
+  ]),
+});
+export const AccountOrganizationSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  slug: z.string().min(1).optional(),
+  role: z.string().min(1),
+  domains: z.array(AccountOrganizationDomainSchema).max(50),
+});
+export const AccountUsageEntrySchema = z.object({
+  id: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  kind: z.enum(['inference', 'generation', 'workspace', 'storage', 'relay', 'deployment']),
+  provider: z.string().min(1),
+  operation: z.string().optional(),
+  credits: z.number().nonnegative(),
+  state: z.enum(['reserved', 'settled', 'released']),
+  externalId: z.string().optional(),
+});
+export const AccountPlanIdSchema = z.enum(['free', 'creator', 'max', 'ultra']);
+export const AccountCatalogSchema = z.object({
+  plans: z.object({
+    free: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    creator: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    max: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    ultra: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+  }),
+  creditPacks: z.record(
+    z.string().min(1),
+    z.object({
+      name: z.string().min(1),
+      credits: z.number().int().positive(),
+      expiresInDays: z.number().int().positive().optional(),
+    }),
+  ),
+});
+export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
+  z.object({ authenticated: z.literal(false), backend: AccountBackendSchema }),
+  z.object({
+    authenticated: z.literal(true),
+    backend: AccountBackendSchema,
+    user: AccountUserSchema,
+    organizations: z.array(AccountOrganizationSchema).max(100).optional(),
+    plan: AccountPlanSchema,
+    credits: AccountCreditsSchema,
+    spendPolicy: AccountSpendPolicySchema,
+    alerts: z.array(AccountAlertSchema).max(100).optional(),
+    entitlements: z.object({
+      generation: z.boolean(),
+      dailyJobs: z.number().int().positive().optional(),
+    }),
+  }),
+]);
+/** Product-facing routes. Provider tools may translate BYOK to their native
+ * transport name (`direct`) internally. */
+export const GenerationExecutionRouteSchema = z.enum(['auto', 'mock', 'managed', 'byok']);
+export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs', 'openrouter']);
+export const CodingInferenceSettingsSchema = z.object({
+  enabled: z.boolean(),
+  provider: z.literal('openrouter'),
+  model: z.string().trim().min(1).max(256),
+});
+export const ProviderCredentialSourceSchema = z.enum(['environment', 'system', 'session', 'none']);
+export const ProviderCredentialStatusSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  label: z.string().min(1),
+  environmentVariable: z.string().min(1),
+  configured: z.boolean(),
+  source: ProviderCredentialSourceSchema,
+  editable: z.boolean(),
+  persistence: z.enum(['system', 'session']),
+  maskedKey: z.string().min(1).optional(),
+  problem: z.string().min(1).optional(),
+});
+export const ProviderCredentialTestResultSchema = z.object({
+  provider: ProviderCredentialIdSchema,
+  ok: z.literal(true),
+  testedAt: z.string().datetime(),
+});
+
+export type AccountBackend = z.infer<typeof AccountBackendSchema>;
+export type AccountPlan = z.infer<typeof AccountPlanSchema>;
+export type AccountCredits = z.infer<typeof AccountCreditsSchema>;
+export type AccountSpendPolicy = z.infer<typeof AccountSpendPolicySchema>;
+export type AccountAlert = z.infer<typeof AccountAlertSchema>;
+export type AccountUser = z.infer<typeof AccountUserSchema>;
+export type AccountOrganization = z.infer<typeof AccountOrganizationSchema>;
+export type AccountOrganizationDomain = z.infer<typeof AccountOrganizationDomainSchema>;
+export type AccountUsageEntry = z.infer<typeof AccountUsageEntrySchema>;
+export type AccountPlanId = z.infer<typeof AccountPlanIdSchema>;
+export type AccountCatalog = z.infer<typeof AccountCatalogSchema>;
+export type AccountSnapshot = z.infer<typeof AccountSnapshotSchema>;
+export type GenerationExecutionRoute = z.infer<typeof GenerationExecutionRouteSchema>;
+export type CodingInferenceSettings = z.infer<typeof CodingInferenceSettingsSchema>;
+export type ProviderCredentialId = z.infer<typeof ProviderCredentialIdSchema>;
+export type ProviderCredentialSource = z.infer<typeof ProviderCredentialSourceSchema>;
+export type ProviderCredentialStatus = z.infer<typeof ProviderCredentialStatusSchema>;
+export type ProviderCredentialTestResult = z.infer<typeof ProviderCredentialTestResultSchema>;
+export type EditorAccountSnapshot = AccountSnapshot & {
+  /** Which identity/payment surface backs this editor session. The in-process
+   * mock value exists only for isolated unit tests. */
+  accountEnvironment: 'test-mock' | 'development-twin' | 'production';
+  routes: { mock: true; managed: boolean; byok: boolean; byokProviders: string[] };
+  preferredRoute: GenerationExecutionRoute;
+  /** Editor-only metadata. Credential values never cross the server boundary. */
+  providerCredentials: ProviderCredentialStatus[];
+  codingInference: CodingInferenceSettings;
+};
+export interface GenerationAccountProjection {
+  routes: EditorAccountSnapshot['routes'];
+  preferredRoute: GenerationExecutionRoute;
+}
+export function generationAccountProjection(
+  account: EditorAccountSnapshot,
+): GenerationAccountProjection {
+  return {
+    routes: {
+      mock: true,
+      managed: account.routes.managed,
+      byok: account.routes.byok,
+      byokProviders: [...account.routes.byokProviders],
+    },
+    preferredRoute: account.preferredRoute,
+  };
+}
+export const EditorAccountSnapshotSchema: z.ZodType<EditorAccountSnapshot> = z.intersection(
+  AccountSnapshotSchema,
+  z.object({
+    accountEnvironment: z.enum(['test-mock', 'development-twin', 'production']),
+    routes: z.object({
+      mock: z.literal(true),
+      managed: z.boolean(),
+      byok: z.boolean(),
+      byokProviders: z.array(z.string().min(1)),
+    }),
+    preferredRoute: GenerationExecutionRouteSchema,
+    providerCredentials: z.array(ProviderCredentialStatusSchema),
+    codingInference: CodingInferenceSettingsSchema,
+  }),
+);

package/src/chrome.ts

@@ -0,0 +1,83 @@
+/**
+ * THE CHROME POINTS — palette actions and menu items a package contributes
+ * (WORKBENCH.md §Contribution points). Both are data: an id, a label and what
+ * happens on choose. The host renders them where its own live: a contributed
+ * action in the command palette beside the editor's, a contributed item at the
+ * end of the named application menu.
+ *
+ *   `profiler.action.ts`   export const point = 'workspace.action';  export const actions: ActionContribution['actions']
+ *   `navmesh.menu.ts`      export const point = 'workspace.menu';    export const menu: MenuContribution
+ *
+ * A contribution's id is namespaced by the host under `tool:` like a
+ * utility's, so it can never collide with an editor action. `disabled` is
+ * asked at render, so an item may follow session state (a bake that has no
+ * navigation adapter to run on).
+ */
+
+export interface ContributedAction {
+  readonly id: string;
+  readonly label: string;
+  readonly execute: () => void | Promise<void>;
+}
+
+export interface ActionContribution {
+  /**
+   * The palette actions — a fixed list, or a function for a LIVE set (one
+   * action per running XState actor): the host asks it when the palette
+   * opens and again whenever `subscribe` fires, the way a menu item's
+   * `disabled` is asked at render.
+   */
+  readonly actions: readonly ContributedAction[] | (() => readonly ContributedAction[]);
+  /** Fires when a live `actions` set moved. Returns the unsubscribe. */
+  readonly subscribe?: (listener: () => void) => () => void;
+}
+
+/** The application menus a package may append to (`edit` is the host's
+ *  own — its verbs are the history's and the selection's), and `asset`: the
+ *  Asset Browser's context menu on one asset, whose items receive the asset. */
+export type ContributableMenu = 'view' | 'window' | 'debug' | 'tools' | 'help' | 'asset';
+
+/** What a context menu's item is invoked ON. Empty for the application menus. */
+export interface MenuSubject {
+  /** The project-relative path of the asset the `asset` menu opened on. */
+  readonly assetPath?: string;
+}
+
+export interface ContributedMenuItem {
+  readonly id: string;
+  readonly label: string | (() => string);
+  readonly execute: (subject: MenuSubject) => void | Promise<void>;
+  readonly disabled?: (subject: MenuSubject) => boolean;
+  /** A `data-testid` for the item, when a driver needs to find it. */
+  readonly testId?: string;
+}
+
+export interface MenuContribution {
+  readonly menu: ContributableMenu;
+  readonly items: readonly ContributedMenuItem[];
+}
+
+/**
+ * A HEADER item (`.header.tsx`, `point = 'workspace.header'`): a component
+ * the host renders in the project header's transport cluster, in `order`.
+ * The Play transport is the worked case — a package that plays a game puts
+ * its play/pause/stop there; a project that declares nothing to run has an
+ * empty cluster.
+ */
+export interface HeaderContribution {
+  readonly order?: number;
+  /**
+   * Where the item renders: the project header's transport cluster (the
+   * default), or the 3D document's toolbar (`object3d-document`), where the
+   * component receives the open document's id and resolves its subject through
+   * its own integration. A runtime debug toggle on a mounted model lives there.
+   */
+  readonly placement?: HeaderPlacement;
+}
+
+export type HeaderPlacement = 'transport' | 'object3d-document';
+
+/** What a `object3d-document` header item is rendered with. */
+export interface DocumentHeaderItemProps {
+  readonly documentId: string;
+}