lumiverse-spindle-types 0.6.18 → 0.6.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/dom.ts

@@ -1,6 +1,7 @@
 import type { PromptBlockDTO, PromptVariableValuesDTO, RequestInitDTO } from "./api";
 import type { SpindleComponentsHelper } from "./components";
 import type { SpindleHostDescriptorV1, SpindleHostLocaleAPI } from "./host";
+import type { SpindleThemeAuthoringAPI } from "./theme";
 
 /** A chat-message DOM element paired with its stable message id. */
 export interface SpindleMessageElement {
@@ -951,6 +952,8 @@ export interface SpindleFrontendContext {
   readonly host: SpindleHostDescriptorV1;
   /** Synchronous host locale access with removable live-change subscriptions. */
   readonly locale: SpindleHostLocaleAPI;
+  /** Native persistent theme authoring. Feature-detect each versioned host capability before use. */
+  readonly theme: SpindleThemeAuthoringAPI;
   dom: SpindleDOMHelper;
   events: {
     on(event: string, handler: (payload: unknown) => void): () => void;

package/src/index.ts

@@ -18,6 +18,23 @@ export {
   SPINDLE_COMPATIBILITY_ERROR_CODE,
 } from "./host";
 
+export type {
+  SpindleThemeAsset,
+  SpindleThemeAssetUploadOptions,
+  SpindleThemeAssetUpdate,
+  SpindleThemePackComponentDraft,
+  SpindleThemePackDraft,
+  SpindleThemePackImportResult,
+  SpindleThemePackInstallOptions,
+  SpindleThemePackInstallResult,
+  SpindleThemeComponentCatalogEntry,
+  SpindleThemeVariableCatalogEntry,
+  SpindleThemeEditorTarget,
+  SpindleThemeEditorOptions,
+  SpindleThemeAuthoringAPI,
+} from "./theme";
+export { SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES } from "./theme";
+
 export type { SpindlePermission as SpindlePermissionType } from "./permissions";
 export { ALL_PERMISSIONS, isValidPermission } from "./permissions";
 

package/src/theme.ts

@@ -0,0 +1,135 @@
+import type { SpindleUploadFile } from "./dom";
+
+/** Frontend-only host capabilities for the native theme-authoring context. */
+export const SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES = Object.freeze({
+  "theme-assets-v1": 1,
+  "theme-packs-v1": 1,
+  "theme-catalog-v1": 1,
+  "theme-editor-navigation-v1": 1,
+} as const);
+
+/** A native theme asset with separate browser and pack-safe references. */
+export interface SpindleThemeAsset {
+  id: string;
+  bundleId: string;
+  slug: string;
+  originalFilename: string;
+  mimeType: string;
+  sizeBytes: number;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  /** Stable path to use from CSS stored in a native theme pack. */
+  cssPath: string;
+  /** Live URL suitable for browser previews and downloads. */
+  contentUrl: string;
+}
+
+export interface SpindleThemeAssetUploadOptions {
+  bundleId: string;
+  slug?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface SpindleThemeAssetUpdate {
+  slug?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+/** CSS-only component input for the canonical native theme-pack adapter. */
+export interface SpindleThemePackComponentDraft {
+  css: string;
+  enabled?: boolean;
+}
+
+/** Authoring input independent of Lumiverse's internal archive representation. */
+export interface SpindleThemePackDraft {
+  name: string;
+  author?: string;
+  description?: string;
+  globalCSS: string;
+  components?: Record<string, SpindleThemePackComponentDraft>;
+  assetBundleId?: string | null;
+}
+
+export interface SpindleThemePackImportResult {
+  draft: SpindleThemePackDraft;
+  assets: SpindleThemeAsset[];
+  warnings: string[];
+}
+
+export interface SpindleThemePackInstallOptions {
+  apply?: boolean;
+  saveToLibrary?: boolean;
+}
+
+export interface SpindleThemePackInstallResult {
+  bundleId: string;
+  applied: boolean;
+  savedToLibrary: boolean;
+  savedThemeId?: string;
+  assetCount: number;
+  componentCount: number;
+}
+
+/** Sanitized native component metadata; source and filesystem paths are omitted. */
+export interface SpindleThemeComponentCatalogEntry {
+  id: string;
+  label: string;
+  category: string;
+  selector: string;
+  hasCss: boolean;
+  hasTsx: boolean;
+}
+
+export interface SpindleThemeVariableCatalogEntry {
+  name: string;
+  defaultValue?: string;
+  value?: string;
+  category?: string;
+}
+
+export type SpindleThemeEditorTarget = "global" | "assets" | "component";
+
+export interface SpindleThemeEditorOptions {
+  target?: SpindleThemeEditorTarget;
+  componentId?: string;
+}
+
+/**
+ * Persistent native theme-authoring integration available to frontend extensions.
+ *
+ * Extensions must feature-detect the corresponding `ctx.host.capabilities` key
+ * before calling a capability group. This surface is distinct from the worker-side
+ * `spindle.theme` live-presentation API.
+ */
+export interface SpindleThemeAuthoringAPI {
+  /** Requires host capability `theme-assets-v1`. Mutations require `app_manipulation`. */
+  readonly assets: {
+    getActiveBundleId(): string | null;
+    createBundle(): string;
+    list(bundleId: string): Promise<SpindleThemeAsset[]>;
+    upload(file: SpindleUploadFile, options: SpindleThemeAssetUploadOptions): Promise<SpindleThemeAsset>;
+    update(assetId: string, patch: SpindleThemeAssetUpdate): Promise<SpindleThemeAsset>;
+    delete(assetId: string): Promise<void>;
+    optimizeWebp(assetId: string): Promise<SpindleThemeAsset>;
+    getBytes(assetId: string): Promise<Uint8Array>;
+  };
+  /** Requires host capability `theme-packs-v1`. Import/install mutations require `app_manipulation`. */
+  readonly packs: {
+    exportDraft(draft: SpindleThemePackDraft): Promise<Uint8Array>;
+    importArchive(bytes: Uint8Array): Promise<SpindleThemePackImportResult>;
+    installDraft(
+      draft: SpindleThemePackDraft,
+      options?: SpindleThemePackInstallOptions,
+    ): Promise<SpindleThemePackInstallResult>;
+  };
+  /** Requires host capability `theme-catalog-v1`. */
+  readonly catalog: {
+    listComponents(): readonly SpindleThemeComponentCatalogEntry[];
+    listVariables(): readonly SpindleThemeVariableCatalogEntry[];
+  };
+  /** Requires host capability `theme-editor-navigation-v1`. */
+  openEditor(options?: SpindleThemeEditorOptions): boolean;
+}

package/test/final-response-and-host-compatibility.test.ts

@@ -4,6 +4,7 @@ import {
   SPINDLE_HOST_CAPABILITIES,
 } from "../src/host";
 import { ALL_PERMISSIONS, isValidPermission } from "../src/permissions";
+import { SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES } from "../src/theme";
 
 test("final-response permission is valid and publicly declared", () => {
   expect(ALL_PERMISSIONS).toContain("final_response");
@@ -30,3 +31,14 @@ test("host compatibility constants are canonical and immutable", () => {
   });
   expect(Object.isFrozen(SPINDLE_HOST_CAPABILITIES)).toBe(true);
 });
+
+test("theme authoring capabilities remain frontend-specific and immutable", () => {
+  expect(SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES).toEqual({
+    "theme-assets-v1": 1,
+    "theme-packs-v1": 1,
+    "theme-catalog-v1": 1,
+    "theme-editor-navigation-v1": 1,
+  });
+  expect(Object.isFrozen(SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES)).toBe(true);
+  expect(SPINDLE_HOST_CAPABILITIES).not.toHaveProperty("theme-assets-v1");
+});

package/test/theme-authoring-consumer.ts

@@ -0,0 +1,55 @@
+import type {
+  SpindleFrontendContext,
+  SpindleThemeComponentCatalogEntry,
+  SpindleThemePackDraft,
+  SpindleUploadFile,
+} from "lumiverse-spindle-types";
+import { SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES } from "lumiverse-spindle-types";
+
+declare const ctx: SpindleFrontendContext;
+declare const upload: SpindleUploadFile;
+declare const archive: Uint8Array;
+
+const themeAssetsVersion: 1 = SPINDLE_THEME_AUTHORING_HOST_CAPABILITIES["theme-assets-v1"];
+void themeAssetsVersion;
+
+const draft: SpindleThemePackDraft = {
+  name: "Visual Theme",
+  globalCSS: ":root { --lumiverse-primary: #c084fc; }",
+  components: {
+    BubbleMessage: { css: "color: var(--lumiverse-text);", enabled: true },
+  },
+};
+
+ctx.theme.assets.upload(upload, { bundleId: "bundle-id" }).then((asset) => {
+  const preview: string = asset.contentUrl;
+  const stylesheetReference: string = asset.cssPath;
+  void preview;
+  void stylesheetReference;
+});
+
+const exported: Promise<Uint8Array> = ctx.theme.packs.exportDraft(draft);
+ctx.theme.packs.importArchive(archive).then((result) => {
+  const imported: SpindleThemePackDraft = result.draft;
+  void imported;
+});
+
+const component: SpindleThemeComponentCatalogEntry = ctx.theme.catalog.listComponents()[0]!;
+const selector: string = component.selector;
+// @ts-expect-error catalog entries intentionally expose no source or filesystem path
+component.cssPath;
+void selector;
+void exported;
+
+const draftWithTsx: SpindleThemePackDraft = {
+  name: "Unsafe input",
+  globalCSS: "",
+  components: {
+    BubbleMessage: {
+      css: "",
+      // @ts-expect-error theme pack drafts deliberately cannot provide component TSX
+      tsx: "export default function Replacement() {}",
+    },
+  },
+};
+void draftWithTsx;

package/tsconfig.consumer.json

@@ -5,5 +5,5 @@
     "outDir": "./.consumer-dist",
     "declaration": false
   },
-  "include": ["test/loom-block-editor-consumer.ts", "test/bound-generation-consumer.ts", "test/interceptor-consumer.ts", "test/host-runtime-contract-consumer.ts", "test/image-gen-stream-consumer.ts"]
+  "include": ["test/loom-block-editor-consumer.ts", "test/bound-generation-consumer.ts", "test/interceptor-consumer.ts", "test/host-runtime-contract-consumer.ts", "test/image-gen-stream-consumer.ts", "test/theme-authoring-consumer.ts"]
 }