@huanlin/dsh-plugin-aigc-canvas 0.1.9 → 0.2.0

package/lib/config.d.ts

@@ -1,14 +1,17 @@
 /**
  * Serializable configuration and defaults for the AIGC canvas host half.
  * The `providers` array holds one or more AIGC provider configs (name /
- * endpoint / apiKey / instructions), editable at runtime through the DSH
- * GUI settings page; cordis.yml `config:` is the first-boot seed only.
+ * endpoint / apiKey / instructions). Since dsh 0.1.7-rc.1 the editable
+ * fields are `.volatile()` members of the entry's profile-owned Cordis
+ * Config (DSH-0.1.7-J1-04): the composition `config:` in cordis.patch.yml is
+ * the first-boot seed only, and runtime edits persist per profile under the
+ * entry id `dsh-aigc-canvas` through the settings service.
  *
  * @module @huanlin/dsh-plugin-aigc-canvas/config
  */
-import z from 'schemastery';
-/** Provider id pattern: lowercase letters, digits, hyphens; must start with a letter. */
-export declare const PROVIDER_ID_PATTERN: RegExp;
+import z from '@deepseek-ai/schemastery';
+import type { Volatile } from '@deepseek-ai/cordis';
+export { PROVIDER_ID_PATTERN, validateProviderId } from './provider-shape.js';
 /** How the aigc_http_request tool attaches the provider apiKey to requests. */
 export interface AigcProviderAuth {
     /**
@@ -34,7 +37,7 @@ export interface AigcProvider {
     name: string;
     /** Provider API endpoint URL. `stub://aigc-backend` = the built-in stub. */
     endpoint: string;
-    /** Provider API key (stored in memory only; set via GUI or cordis.yml). */
+    /** Provider API key (persisted with the entry config in cordis.patch.yml; set via GUI or seed). */
     apiKey: string;
     /** Free-form usage instructions the agent reads via aigc_get_provider_info. */
     instructions: string;
@@ -52,8 +55,29 @@ export interface AigcCanvasConfig {
     /** Maximum media bytes to write to disk per generated asset. */
     mediaSizeLimit?: number;
 }
-/** Schemastery schema for the plugin configuration. */
-export declare const Config: z<AigcCanvasConfig>;
+/**
+ * The live Cordis config the Loader passes to `apply`.
+ *
+ * `providers` is `.volatile()`: the field arrives as a stable reference whose
+ * `.get()` always returns the latest accepted value (a committed settings
+ * edit updates it in place without remounting the plugin). The other fields
+ * are composition-seed knobs resolved once at load.
+ */
+export interface AigcEntryConfig {
+    /** Live provider list reference; `.get()` returns the latest accepted value. */
+    providers?: Volatile<readonly AigcProvider[]>;
+    requestTimeoutMs?: number;
+    mediaSizeLimit?: number;
+}
+/**
+ * Schemastery schema for the plugin's profile-owned Config.
+ *
+ * `providers` is `.volatile()` (dsh 0.1.7-rc.1 DSH-0.1.7-J1-04): the settings
+ * service enumerates the entry's volatile fields for the configuration form,
+ * and a committed edit updates the running reference in place. The numeric
+ * knobs stay non-volatile (cordis.patch.yml seed only).
+ */
+export declare const Config: z<AigcEntryConfig>;
 /** A fully-resolved provider (all fields guaranteed). */
 export interface ResolvedAigcProvider extends AigcProvider {
     name: string;
@@ -71,7 +95,21 @@ export interface ResolvedAigcConfig {
 }
 /** Returns true when the provider endpoint points at the built-in stub backend. */
 export declare function isStubEndpoint(endpoint: string): boolean;
-/** Validate a provider id; returns an error message or undefined if valid. */
-export declare function validateProviderId(id: string): string | undefined;
-/** Apply direct-call defaults after Loader schema validation has normally run. */
-export declare function resolveAigcConfig(config: AigcCanvasConfig | undefined): ResolvedAigcConfig;
+/**
+ * Normalize a raw provider list (the volatile reference's latest snapshot, a
+ * legacy imported document, or a hand-edited override) into resolved
+ * providers. Non-object entries are skipped; duplicate ids keep the first
+ * occurrence (insertion order preserved).
+ * @param raw - the raw list value.
+ * @returns the resolved providers, in order, deduplicated by id.
+ */
+export declare function resolveAigcProviders(raw: unknown): readonly ResolvedAigcProvider[];
+/**
+ * Resolve the apply-time seed config (direct-call defaults after Loader
+ * schema validation has normally run). The provider list reads the live
+ * volatile reference; when it resolves empty at load, the default stub is
+ * seeded so the tools always have one provider.
+ * @param config - the entry config the Loader passed to `apply`.
+ * @returns the fully defaulted seed settings.
+ */
+export declare function resolveAigcConfig(config: AigcEntryConfig | undefined): ResolvedAigcConfig;

package/lib/context-types.d.ts

@@ -1,114 +1,140 @@
-/**
- * Structural types for the cordis services this plugin consumes, plus the
- * Context augmentation both halves share. A third-party plugin resolves
- * outside the DSH monorepo's single cordis instance, so the upstream
- * `declare module 'cordis'` augmentations do not reach this Context — and
- * the npm cordis package does not declare the DSH-vendored runtime members
- * (`ctx.effect`, the webServer/sessions/loader faces). The members below
- * mirror the actual runtime shapes this plugin touches:
- *
- * - webServer: @deepseek-ai/dsh-host-webserver
- * - sessions:   @deepseek-ai/dsh-session (host side)
- * - loader:     @cordisjs/plugin-loader (entry options)
- * - effect:     the DSH-vendored cordis lifecycle helper
- *
- * Drift from upstream is contained to this file.
- */
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { Duplex } from 'node:stream';
-import type { Context } from 'cordis';
-import type { AigcCanvasService } from './canvas-registry.js';
-/** One named webserver route (mirror of the host-webserver WebRoute). */
-export interface AigcWebRoute {
-    kind: 'exact' | 'prefix';
-    path: string;
-    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
-}
-/** One exact-path HTTP upgrade registration (mirror of WebUpgradeRoute). */
-export interface AigcWebUpgradeRoute {
-    path: string;
-    handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
-}
-/** The webServer service face this plugin uses. */
-export interface AigcWebServer {
-    register(route: AigcWebRoute): () => void;
-    registerUpgrade(route: AigcWebUpgradeRoute): () => void;
-}
-/** A published session's header slice (authoritative cwd). */
-export interface AigcSessionHeader {
-    cwd?: string;
-}
-/** The host session store face (`ctx.sessions.get(id)` returns the live session). */
-export interface AigcSessionStore {
-    get(id: string): {
-        header: AigcSessionHeader;
-    } | undefined;
-}
-/**
- * The minimal Agent face this plugin uses for context injection.
- * Mirrors `@deepseek-ai/dsh-agent`'s `Agent.inject()` — see the DSH
- * agent loop's inbox/splice path. The plugin calls `inject()` to push
- * a notice into the agent's next-step context (non-waking).
- */
-export interface AigcAgent {
-    readonly id: string;
-    inject(message: AigcUserMessage): void;
-}
-/** A minimal user-role message for agent.inject (mirrors dsh-llm's UserMessage). */
-export interface AigcUserMessage {
-    readonly id: string;
-    readonly role: 'user';
-    readonly content: ReadonlyArray<{
-        type: 'text';
-        text: string;
-    }>;
-    readonly source: {
-        readonly kind: 'plugin';
-        readonly plugin: string;
-        readonly form?: 'notice';
-        readonly summary?: string;
-    };
-}
-/** The agents registry face (`ctx.agents.get(sessionId)` returns the live agent). */
-export interface AigcAgentRegistry {
-    get(id: string): AigcAgent | undefined;
-}
-/** One loader entry's options slice (the connection row's resolved config). */
-export interface AigcLoaderEntry {
-    options: {
-        name: string;
-        config?: unknown;
-    };
-}
-/** The loader face used to read the connection row's trustedHosts config. */
-export interface AigcLoader {
-    entries(): Iterable<AigcLoaderEntry>;
-}
-/**
- * The tools service face restated.
- * Mirrored here exactly like better-sidebar does — the dual-cordis-instance
- * resolution otherwise hides the upstream augmentation. The `tools` service
- * face is declared in `./types.d.ts` (the ambient cordis module augmentation)
- * and not restated here to avoid a "subsequent property declarations must
- * have the same type" error.
- */
-export interface AigcToolsService {
-    register(tool: unknown): () => void;
-}
-declare module 'cordis' {
-    interface Context {
-        webServer: AigcWebServer;
-        sessions: AigcSessionStore;
-        agents: AigcAgentRegistry;
-        loader: AigcLoader;
-        /**
-         * The host-side AIGC canvas registry: holds the per-session element
-         * table (prompts + generated assets) and edges. Provided by the host
-         * half (see {@link ./canvas-registry.ts}); undefined on the client.
-         */
-        aigcCanvas: AigcCanvasService;
-        /** Register a lifecycle callback (DSH-vendored cordis). */
-        effect(fn: () => void | (() => void), label?: string): void;
-    }
-}
-export type { Context };
+/**
+ * Structural types for the cordis services this plugin consumes, plus the
+ * Context augmentation both halves share. A third-party plugin resolves
+ * outside the DSH monorepo's single cordis instance, so the upstream
+ * `declare module 'cordis'` augmentations do not reach this Context — and
+ * the npm cordis package does not declare the DSH-vendored runtime members
+ * (`ctx.effect`, the webServer/sessions/loader faces). The members below
+ * mirror the actual runtime shapes this plugin touches:
+ *
+ * - webServer: @deepseek-ai/dsh-host-webserver
+ * - sessions:   @deepseek-ai/dsh-session (host side)
+ * - loader:     @cordisjs/plugin-loader (entry options)
+ * - effect:     the DSH-vendored cordis lifecycle helper
+ *
+ * Drift from upstream is contained to this file.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Context } from 'cordis';
+import type { AigcCanvasService } from './canvas-registry.js';
+/** One named webserver route (mirror of the host-webserver WebRoute). */
+export interface AigcWebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** One exact-path HTTP upgrade registration (mirror of WebUpgradeRoute). */
+export interface AigcWebUpgradeRoute {
+    path: string;
+    handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
+}
+/** The webServer service face this plugin uses. */
+export interface AigcWebServer {
+    register(route: AigcWebRoute): () => void;
+    registerUpgrade(route: AigcWebUpgradeRoute): () => void;
+}
+/** A published session's header slice (authoritative cwd). */
+export interface AigcSessionHeader {
+    cwd?: string;
+}
+/** The host session store face (`ctx.sessions.get(id)` returns the live session). */
+export interface AigcSessionStore {
+    get(id: string): {
+        header: AigcSessionHeader;
+    } | undefined;
+}
+/**
+ * The minimal Agent face this plugin uses for context injection.
+ * Mirrors `@deepseek-ai/dsh-agent`'s `Agent.inject()` — see the DSH
+ * agent loop's inbox/splice path. The plugin calls `inject()` to push
+ * a notice into the agent's next-step context (non-waking).
+ */
+export interface AigcAgent {
+    readonly id: string;
+    inject(message: AigcUserMessage): void;
+}
+/** A minimal user-role message for agent.inject (mirrors dsh-llm's UserMessage). */
+export interface AigcUserMessage {
+    readonly id: string;
+    readonly role: 'user';
+    readonly content: ReadonlyArray<{
+        type: 'text';
+        text: string;
+    }>;
+    readonly source: {
+        readonly kind: 'plugin';
+        readonly plugin: string;
+        readonly form?: 'notice';
+        readonly summary?: string;
+    };
+}
+/** The agents registry face (`ctx.agents.get(sessionId)` returns the live agent). */
+export interface AigcAgentRegistry {
+    get(id: string): AigcAgent | undefined;
+}
+/** One loader entry's options slice (the connection row's resolved config). */
+export interface AigcLoaderEntry {
+    options: {
+        name: string;
+        config?: unknown;
+    };
+}
+/** The loader face used to read the connection row's trustedHosts config. */
+export interface AigcLoader {
+    entries(): Iterable<AigcLoaderEntry>;
+}
+/**
+ * The settings service face this plugin uses (mirror of
+ * `@deepseek-ai/dsh-settings` `SettingsForms`, dsh 0.1.7-rc.1). Restated
+ * structurally like the other faces above so the third-party resolution
+ * tree typechecks without a dependency on the DSH package.
+ */
+export interface AigcSettingsForms {
+    /** Register the calling plugin instance's settings-page policy. */
+    configure(presentation: {
+        auto?: boolean;
+    }, owner?: AigcCordisFiber): () => void;
+    /** Merge editable (volatile) fields into one entry's profile config. */
+    update(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+}
+/**
+ * Structural slice of the DSH-vendored cordis `Fiber`: `configure` keys its
+ * presentation policy by fiber identity, and the plugin only ever passes
+ * `ctx.fiber` through.
+ */
+export interface AigcCordisFiber {
+    readonly uid: number | null;
+}
+/**
+ * The tools service face restated.
+ * Mirrored here exactly like better-sidebar does — the dual-cordis-instance
+ * resolution otherwise hides the upstream augmentation. The `tools` service
+ * face is declared in `./types.d.ts` (the ambient cordis module augmentation)
+ * and not restated here to avoid a "subsequent property declarations must
+ * have the same type" error.
+ */
+export interface AigcToolsService {
+    register(tool: unknown): () => void;
+}
+declare module 'cordis' {
+    interface Context {
+        webServer: AigcWebServer;
+        sessions: AigcSessionStore;
+        agents: AigcAgentRegistry;
+        loader: AigcLoader;
+        /** The profile-owned settings forms service (dsh 0.1.7-rc.1); undefined when no settings provider is mounted. */
+        settings: AigcSettingsForms;
+        /** The plugin instance's fiber (DSH-vendored cordis). */
+        fiber: AigcCordisFiber;
+        /**
+         * The host-side AIGC canvas registry: holds the per-session element
+         * table (prompts + generated assets) and edges. Provided by the host
+         * half (see {@link ./canvas-registry.ts}); undefined on the client.
+         */
+        aigcCanvas: AigcCanvasService;
+        /** Register a lifecycle callback (DSH-vendored cordis). */
+        effect(fn: () => void | (() => void), label?: string): void;
+    }
+}
+export type { Context };

package/lib/entry-identity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * entry-identity.ts — the identity triple that binds this plugin's three
+ * naming surfaces together. Keeping them in one dependency-free module lets
+ * a unit test pin them against `cordis.patch.yml` and `package.json`
+ * (a mismatched `plugins.row.config` key fails silently: the row's configure
+ * entry simply never appears).
+ *
+ *  - ENTRY_ID: the profile entry id — the `id` of the insert row in
+ *    `cordis.patch.yml`. The Host serves the entry's volatile config under
+ *    it, so it keys `ctx.configForms.get` and `settings.update`.
+ *  - PACKAGE_NAME: the bundle's npm package name — the row's `name` field.
+ *  - ROW_CONFIG_KEY: the Plugins page `plugins.row.config` slot key,
+ *    `<package name>#<row id>` with the row id passed through verbatim.
+ *
+ * @module @huanlin/dsh-plugin-aigc-canvas/entry-identity
+ */
+/** Profile entry id (= the `cordis.patch.yml` insert row id / settings namespace). */
+export declare const ENTRY_ID = "dsh-aigc-canvas";
+/** Bundle package name (the Loader resolves the row's module through it). */
+export declare const PACKAGE_NAME = "@huanlin/dsh-plugin-aigc-canvas";
+/** `plugins.row.config` key: the bundle's package name `#` the patch row id. */
+export declare const ROW_CONFIG_KEY = "@huanlin/dsh-plugin-aigc-canvas#dsh-aigc-canvas";

package/lib/index.d.ts

@@ -1,7 +1,9 @@
 import type { Context } from './context-types.js';
-import { Config, type AigcCanvasConfig, type AigcProvider, type ResolvedAigcConfig, type ResolvedAigcProvider } from './config.js';
-export { Config };
-export type { AigcCanvasConfig, AigcProvider, ResolvedAigcConfig, ResolvedAigcProvider };
+import { Config, type AigcEntryConfig, type AigcProvider, type ResolvedAigcConfig, type ResolvedAigcProvider } from './config.js';
+import { SETTINGS_NAMESPACE } from './settings.js';
+export { Config, SETTINGS_NAMESPACE };
+export type { AigcCanvasConfig } from './config.js';
+export type { AigcEntryConfig, AigcProvider, ResolvedAigcConfig, ResolvedAigcProvider };
 export type { Context } from './context-types.js';
 export type { AigcCanvasService, AigcElement, AigcEdge, AigcCanvasState, AigcElementKind, } from './canvas-registry.js';
 /** Plugin identity for cordis.yml rows. */
@@ -9,4 +11,4 @@ export declare const name = "dsh-aigc-canvas";
 /** Services required before mounting. */
 export declare const inject: string[];
 /** Plugin body. */
-export declare function apply(ctx: Context, config?: AigcCanvasConfig): void;
+export declare function apply(ctx: Context, config?: AigcEntryConfig): void;