@dsh-ft/dsh-fft-settings 0.0.0-stage → 0.5.1

package/src/agent.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent-plane entry for the FT prompt contract.
+ *
+ * Mounted by an agent preset so the contract exists only for that preset's
+ * agents; the package's host entry keeps providing the settings service and
+ * must not be mounted from a preset (a service row there needs an isolate
+ * realm). The texts and the registration both live in `./guidance.ts`, so this
+ * entry adds no second copy.
+ * @module @dsh-ft/dsh-fft-settings/agent
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { installGuidance } from './guidance.js'
+
+/** Cordis plugin name. */
+export const name = '@dsh-ft/dsh-fft-settings/agent'
+
+/**
+ * The prompt registry this entry contributes to. `ftshareSettings` is optional
+ * and mounted in `installGuidance`, so a missing settings row costs only the
+ * credential fact instead of the whole contract.
+ */
+export const inject = ['systemPrompt']
+
+/**
+ * Register the FT prompt contract in the mounting scope.
+ * @param ctx - the preset subtree's context; the preset's agents are the scope.
+ */
+export function apply(ctx: Context): void {
+  installGuidance(ctx)
+}

package/src/brand.ts

@@ -0,0 +1,79 @@
+/**
+ * FT brand tokens published as a host theme override layer.
+ *
+ * The layer only *adds* brand variables on `body`; it never overrides a
+ * `--dsw-alias-*` value, so host chrome keeps its own palette and any user
+ * theme keeps working underneath. Consumers read `var(--ft-*)` with the same
+ * value as their fallback: the layer is a convenience, not a dependency, so
+ * every sub-plugin keeps its brand colors when this plugin is absent (or when
+ * the host has no `theme` service at all). Scheme-invariant tokens repeat one
+ * value; palette-aware tokens spell both with `light-dark()`.
+ *
+ * Keep those fallbacks equal to {@link FT_BRAND_TOKENS}; `tests/brand.test.mjs`
+ * scans every package for the pairing and fails on a drift.
+ */
+
+/** One token value per palette mode; the host rejects a bare string. */
+export interface BrandTokenModes {
+  readonly light: string
+  readonly dark: string
+}
+
+/** One value for both palettes: brand fills are scheme-invariant. */
+const invariant = (value: string): BrandTokenModes => ({ light: value, dark: value })
+
+/** Layer identity reported to `ctx.theme.overrideTokens` (one layer per source). */
+export const FT_BRAND_SOURCE = '@dsh-ft/dsh-fft-settings'
+
+/**
+ * The published brand colors.
+ *
+ * `accent` is the FT yellow used by this plugin's primary action and eyebrow;
+ * `accent-warm` is the orange trading accent shared by market and trade
+ * surfaces (it is the only palette-aware group); `wechat` is the enterprise-
+ * WeChat green the SSO card keeps as its identity. Inks are the text colors on
+ * those fills, and `-soft` is the tinted surface behind the accent.
+ */
+export const FT_BRAND_TOKENS: Readonly<Record<string, BrandTokenModes>> = Object.freeze({
+  '--ft-accent': invariant('#f0c433'),
+  '--ft-accent-ink': invariant('#171717'),
+  '--ft-accent-warm': { light: '#cf5623', dark: '#ff8352' },
+  '--ft-accent-warm-hover': { light: '#b8481b', dark: '#ff9a72' },
+  '--ft-accent-warm-ink': { light: '#ffffff', dark: '#1a120e' },
+  '--ft-accent-warm-soft': { light: '#fbeee8', dark: '#2b1d16' },
+  '--ft-wechat': invariant('#2ebd68'),
+  '--ft-wechat-ink': invariant('#102419'),
+})
+
+/** The slice of the host theme service this layer uses. */
+export interface BrandThemeService {
+  overrideTokens(source: string, tokens: Readonly<Record<string, BrandTokenModes>>): () => void
+}
+
+/** Scoped context delivered once the `theme` service is available. */
+export interface BrandThemeScope {
+  readonly theme: BrandThemeService
+  effect(callback: () => () => void, label: string): void
+}
+
+/** The slice of the client context this layer needs: a deferred service inject. */
+export interface BrandThemeContext {
+  inject(deps: readonly string[], callback: (scope: BrandThemeScope) => void): void
+}
+
+/**
+ * Stack the brand layer once the host theme service exists.
+ *
+ * The deferred `inject` is deliberate: this plugin's declared client context
+ * names only the services its cards read, and a host without `theme` must
+ * still load the settings page — the CSS fallbacks then carry the colors.
+ * @param ctx - client context carrying the host theme service.
+ */
+export function applyBrandTokens(ctx: BrandThemeContext): void {
+  ctx.inject(['theme'], (scope) => {
+    scope.effect(
+      () => scope.theme.overrideTokens(FT_BRAND_SOURCE, FT_BRAND_TOKENS),
+      'ft-settings: FT brand tokens',
+    )
+  })
+}

package/src/client.tsx

@@ -0,0 +1,21 @@
+import { registerApiKeyCard, type ApiKeyCardContext } from './features/api-key/card.js'
+import { registerLogsCard } from './features/logs/card.js'
+import { registerSettingsSection } from './core/shell.js'
+import { applyBrandTokens, type BrandThemeContext } from './brand.js'
+export * from './core/shell.js'
+/** Browser context this plugin's own client half requires. */
+export type FtshareSettingsClientContext = ApiKeyCardContext
+export const inject = ['slots', 'remote']
+export function apply(ctx: FtshareSettingsClientContext): void {
+  registerFtshareSettings(ctx)
+  // The declared context above names only the services the cards read; the
+  // brand layer defers on `theme` through the full Cordis context, so this
+  // plugin still loads on a host without the theme service.
+  applyBrandTokens(ctx as unknown as BrandThemeContext)
+}
+/** Contribute the section shell, then the built-in cards through the slot it declares. */
+export function registerFtshareSettings(ctx: FtshareSettingsClientContext): void {
+  registerSettingsSection(ctx)
+  registerApiKeyCard(ctx)
+  registerLogsCard(ctx)
+}

package/src/contract.ts

@@ -0,0 +1,14 @@
+/**
+ * `@dsh-ft/dsh-fft-settings/contract` — the aggregate contract entry.
+ *
+ * Re-exports the generic seam contract plus every built-in feature contract,
+ * so `FtshareSettingsService`, the route constants and the API Key / logs
+ * vocabulary keep arriving from one import. It has no Node runtime dependency, so it is
+ * safe in a browser bundle and in a host plugin alike. Two type sources feed
+ * it: the Host contract (`./core/contract.js` plus each feature contract) and,
+ * for UI composition, `@dsh-ft/dsh-fft-settings/client`, which merges the card
+ * slot into the renderer's SlotMap.
+ */
+export * from './core/contract.js'
+export * from './features/api-key/contract.js'
+export * from './features/logs/contract.js'

package/src/core/client-transport.ts

@@ -0,0 +1,37 @@
+/**
+ * Browser half of the settings transport.
+ *
+ * Calls are same-origin fetches to the plugin route, so the browser session
+ * cookie carries authentication and this plugin needs no Connection RPC client.
+ */
+
+import { FTSHARE_SETTINGS_ROUTE } from './contract.js'
+import type { ClientTransport, RpcResult } from './rpc-core.js'
+
+/** Transport this caller posts through; same signature as the global `fetch`. */
+export type SettingsFetch = (input: string, init: RequestInit) => Promise<Response>
+
+/**
+ * Create the browser-backed caller used by the settings cards.
+ * @param doFetch - transport override; defaults to the page's global fetch.
+ * @returns caller that owns request encoding and envelope decoding.
+ */
+export function createSettingsTransport(doFetch?: SettingsFetch): ClientTransport {
+  const send: SettingsFetch = doFetch ?? ((input, init) => globalThis.fetch(input, init))
+  return {
+    async call(endpoint, payload = {}, signal) {
+      const response = await send(FTSHARE_SETTINGS_ROUTE, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ endpoint, payload }),
+        ...signal === undefined ? {} : { signal },
+      })
+      if (!response.ok) {
+        // The carrier answers 401/403 before dispatch; anything else is a route
+        // or plugin-level failure. Both are transport failures for the caller.
+        throw new Error(`transport failure for ${endpoint}: HTTP ${response.status}`)
+      }
+      return await response.json() as RpcResult<unknown>
+    },
+  }
+}

package/src/core/contract.ts

@@ -0,0 +1,57 @@
+/**
+ * Generic half of the settings contract: the seam's identity, its transport
+ * constants, and the service shape. It carries no feature vocabulary — a
+ * feature's own contract lives beside that feature and merges into
+ * {@link FtshareSettingsNamespaces}.
+ */
+import type { FtshareSettingsModuleRegistry } from './module-registry.js'
+export type { FtshareSettingsModuleRegistry, SettingsModule, SettingsRegistration } from './module-registry.js'
+export type { SettingsRpcMethod, SettingsRpcMethods } from './rpc-core.js'
+/** Protocol version of the settings route and envelope. */
+export const FTSHARE_SETTINGS_API_VERSION = 1 as const
+/**
+ * Identity of the settings section that carries this plugin's cards.
+ *
+ * The id replaces the old `ftshare`. The label is a neutral product name, not
+ * the internal brand: the page ships publicly, and the data source it
+ * integrates is named inside the cards instead.
+ */
+export const FTSHARE_SETTINGS_SECTION = { id: 'dsh-fft', order: 120, label: '金融终端' } as const
+/**
+ * Child slot of {@link FTSHARE_SETTINGS_SECTION} that carries its cards.
+ *
+ * The section declares the slot when it registers; every card — ours and a
+ * third party's — contributes through it with `id`/`order`/`label`, and
+ * `order` (ascending, default 100) decides the card's position.
+ */
+export const FTSHARE_SETTINGS_CARD_SLOT = 'ftshare.settings.card' as const
+/**
+ * Browser-facing route for this plugin's settings calls.
+ *
+ * It sits below `/api` so the shared connection carrier applies the Host/Origin
+ * fence and browser authentication before dispatch; this plugin only handles
+ * the call itself.
+ */
+export const FTSHARE_SETTINGS_ROUTE = '/api/ftshare-settings' as const
+/** Largest request body accepted on {@link FTSHARE_SETTINGS_ROUTE}. */
+export const FTSHARE_SETTINGS_MAX_BODY_BYTES = 64 * 1024
+/**
+ * Merge point for namespaces a package reads but does not produce. A producer
+ * gets its type from `register` inference; a consumer that reads someone
+ * else's namespace declares one line, e.g. `cockpit: CockpitSettings`. Each
+ * built-in feature merges its own line from its own feature directory.
+ */
+export interface FtshareSettingsNamespaces {}
+/**
+ * Host service published as `ctx.ftshareSettings`.
+ *
+ * `apiVersion` and `modules` are permanent; every other member appears only
+ * while its namespace is registered, so consumers must read properties at call
+ * time instead of caching them during their own apply.
+ */
+export type FtshareSettingsService =
+  & {
+    readonly apiVersion: typeof FTSHARE_SETTINGS_API_VERSION
+    readonly modules: FtshareSettingsModuleRegistry
+  }
+  & { readonly [N in keyof FtshareSettingsNamespaces & string]: FtshareSettingsNamespaces[N] }

package/src/core/module-registry.ts

@@ -0,0 +1,102 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { FTSHARE_SETTINGS_API_VERSION, type FtshareSettingsService } from './contract.js'
+import { assertSettingsName, assertSettingsRpcModule, createSettingsRpcHandler, type SettingsRpcHandler, type SettingsRpcMethods } from './rpc-core.js'
+
+/**
+ * One contribution to the settings service: a namespace, the host services it
+ * needs, and a synchronous factory for its service instance and RPC methods.
+ * Third parties may write this shape structurally; `defineSettingsModule` only
+ * buys type inference.
+ */
+export interface SettingsModule<N extends string = string, S = unknown> {
+  /** Namespace: the RPC endpoint prefix and the service property name. */
+  readonly namespace: N
+  /** Host services this module resolves on its owner context at registration. */
+  readonly inject: readonly string[]
+  /** Register lifecycle cleanup through ctx.effect/on; never return browser secrets as RPC methods. */
+  create(ctx: Context): { service: S; rpcMethods: SettingsRpcMethods }
+}
+export function defineSettingsModule<const N extends string, S>(module: SettingsModule<N, S>): SettingsModule<N, S> { return module }
+/** Handle returned by {@link FtshareSettingsModuleRegistry.register}. */
+export interface SettingsRegistration<N extends string = string, S = unknown> {
+  readonly namespace: N
+  readonly service: S
+  /** Idempotent; also runs when the owner fiber releases. */
+  dispose(): void
+}
+/** Live namespace registry behind `ctx.ftshareSettings.modules`. */
+export interface FtshareSettingsModuleRegistry {
+  register<const N extends string, S>(module: SettingsModule<N, S>, owner: Context): SettingsRegistration<N, S>
+  /** Namespaces currently published on the service object, in registration order. */
+  namespaces(): readonly string[]
+}
+/** The host half assembled by {@link createSettingsHost}. */
+export interface FtshareSettingsHost {
+  /** Service object published as `ctx.ftshareSettings`; namespaces appear on it at runtime. */
+  readonly service: FtshareSettingsService
+  /** Live dispatch table; mount it once and let namespaces come and go. */
+  readonly handler: SettingsRpcHandler
+}
+
+/**
+ * Assemble the host half of the seam: one service object plus one live route
+ * table that namespaces register into.
+ *
+ * Registration is validate-then-write: a bad namespace, a reserved name, a
+ * duplicate, or an unresolvable `module.inject` entry throws before `create`
+ * runs and leaves no service property or route behind. A successful
+ * registration installs a release effect on the owner fiber, so unloading the
+ * owner removes the service property and every route of that namespace
+ * together; the returned `dispose()` is idempotent and equivalent.
+ * @returns the service object and its route table.
+ */
+export function createSettingsHost(): FtshareSettingsHost {
+  const handler = createSettingsRpcHandler()
+  /** Namespaces published by this host, in registration order. */
+  const published = new Map<string, SettingsRegistration<string, unknown>>()
+  const target: Record<string, unknown> = { apiVersion: FTSHARE_SETTINGS_API_VERSION }
+
+  function register<N extends string, S>(module: SettingsModule<N, S>, owner: Context): SettingsRegistration<N, S> {
+    // Validate everything knowable before the first write. `rpcMethods` exists
+    // only after `create`, so its endpoint names are checked immediately after,
+    // still before this registration publishes anything.
+    assertSettingsName(module.namespace)
+    if (published.has(module.namespace)) throw new Error(`Duplicate settings namespace: ${module.namespace}`)
+    for (const name of module.inject) {
+      if (owner.get(name) === undefined) throw new Error(`Missing settings module dependency for ${module.namespace}: ${name}`)
+    }
+    let released = false
+    let committed = false
+    let instance: S | undefined
+    const release = (): void => {
+      if (released) return
+      released = true
+      if (!committed) return
+      if (target[module.namespace] === instance) delete target[module.namespace]
+      if (published.get(module.namespace) === registration) {
+        published.delete(module.namespace)
+        handler.unregister(module.namespace)
+      }
+    }
+    const registration: SettingsRegistration<N, S> = {
+      namespace: module.namespace,
+      get service() { return instance as S },
+      dispose() { release() },
+    }
+    // Install the release effect first: an inactive owner then fails before
+    // this module allocates anything of its own.
+    owner.effect(() => release, `dsh-fft-settings: namespace ${module.namespace}`)
+    const created = module.create(owner)
+    instance = created.service
+    assertSettingsRpcModule({ namespace: module.namespace, rpcMethods: created.rpcMethods })
+    handler.register({ namespace: module.namespace, rpcMethods: created.rpcMethods })
+    Object.defineProperty(target, module.namespace, { value: created.service, enumerable: true, writable: true, configurable: true })
+    published.set(module.namespace, registration as SettingsRegistration<string, unknown>)
+    committed = true
+    return registration
+  }
+
+  const registry: FtshareSettingsModuleRegistry = { register, namespaces: () => [...published.keys()] }
+  target.modules = registry
+  return { service: target as unknown as FtshareSettingsService, handler }
+}

package/src/core/rpc-core.ts

@@ -0,0 +1,107 @@
+import type { FTSHARE_SETTINGS_ROUTE } from './contract.js'
+export interface RpcResult<T> { ok: boolean; value?: T; error?: { code: string; message: string; details: Record<string, unknown> } }
+/** Browser caller for this plugin's route. */
+export interface ClientTransport { call(endpoint: string, payload?: unknown, signal?: AbortSignal): Promise<RpcResult<unknown>> }
+export type RpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<RpcResult<unknown>>
+/** Structural shape of one exact Fetch route; `connection.fetch.register` accepts it. */
+export interface SettingsRoute {
+  readonly path: typeof FTSHARE_SETTINGS_ROUTE
+  readonly methods: readonly string[]
+  readonly requestBody: 'buffered' | 'streaming'
+  readonly fetch: (request: Request) => Promise<Response>
+}
+/** Host registry for exact Fetch routes on the shared `/api` carrier. */
+export interface HostFetch { register(route: SettingsRoute): () => Promise<void> }
+export interface SettingsRpcMethod {
+  validate(payload: unknown): boolean
+  invoke(payload: unknown, signal: AbortSignal): unknown | Promise<unknown>
+}
+export type SettingsRpcMethods = Readonly<Record<string, SettingsRpcMethod>>
+export interface SettingsRpcModule { namespace: string; rpcMethods: SettingsRpcMethods }
+/**
+ * Live dispatch table behind {@link createSettingsRpcHandler}: routes appear
+ * when a namespace is registered and disappear when it is released, so the one
+ * route mounted at boot keeps serving namespaces that arrive later.
+ */
+export interface SettingsRpcTable {
+  /** Validate one whole module, then publish its routes; a failure writes nothing. */
+  register(module: SettingsRpcModule): void
+  /** Remove one namespace and every route under it; unknown namespaces are a no-op. */
+  unregister(namespace: string): void
+  /** Namespaces currently owning at least one route, in registration order. */
+  namespaces(): readonly string[]
+}
+/** The dispatcher callable plus the increment/decrement surface of its route table. */
+export type SettingsRpcHandler = RpcHandler & SettingsRpcTable
+const fail = (code: string, message: string): RpcResult<unknown> => ({ ok: false, error: { code, message, details: {} } })
+/** Names the service object and the route table reserve for themselves. */
+export const SETTINGS_RESERVED_NAMES = ['apiVersion', 'modules', 'constructor', 'prototype', '__proto__'] as const
+export function assertSettingsName(name: string): void {
+  if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name) || (SETTINGS_RESERVED_NAMES as readonly string[]).includes(name)) throw new Error(`Invalid settings name: ${name}`)
+}
+/** Validate every endpoint part of one module without writing to any table. */
+export function assertSettingsRpcModule(module: SettingsRpcModule): void {
+  assertSettingsName(module.namespace)
+  for (const name of Object.keys(module.rpcMethods)) assertSettingsName(name)
+}
+/**
+ * Build the live dispatcher for this plugin's route.
+ *
+ * Only explicitly registered methods are callable; never reflects over a
+ * service. The returned function carries its own route table, so the caller
+ * mounts the route once and mutates through `register` / `unregister`
+ * afterwards. Each `register` validates the whole module first — namespace
+ * format, reserved names, duplicates, and every method name — and writes
+ * nothing when any check fails.
+ * @param modules - optional initial namespaces, registered in order.
+ * @returns dispatcher with the live route table attached.
+ */
+export function createSettingsRpcHandler(modules: readonly SettingsRpcModule[] = []): SettingsRpcHandler {
+  const routes = new Map<string, SettingsRpcMethod>()
+  const namespaces = new Set<string>()
+  const register = (module: SettingsRpcModule): void => {
+    assertSettingsRpcModule(module)
+    if (namespaces.has(module.namespace)) throw new Error(`Duplicate settings namespace: ${module.namespace}`)
+    // Committed: every check above ran before the first write.
+    namespaces.add(module.namespace)
+    for (const [name, method] of Object.entries(module.rpcMethods)) routes.set(`${module.namespace}/${name}`, method)
+  }
+  const unregister = (namespace: string): void => {
+    if (!namespaces.delete(namespace)) return
+    const prefix = `${namespace}/`
+    for (const endpoint of [...routes.keys()]) if (endpoint.startsWith(prefix)) routes.delete(endpoint)
+  }
+  const handler = (async (endpoint: string, payload: unknown, signal: AbortSignal): Promise<RpcResult<unknown>> => {
+    const method = routes.get(endpoint)
+    if (!method) return fail('not_found', '接口不存在')
+    if (signal.aborted) return fail('cancelled', '请求已取消')
+    try {
+      if (!method.validate(payload)) return fail('bad_request', '请求参数不正确')
+      return { ok: true, value: (await method.invoke(payload, signal)) ?? null }
+    } catch { return fail('operation_failed', '操作失败，请刷新状态后重试') }
+  }) as SettingsRpcHandler
+  handler.register = register
+  handler.unregister = unregister
+  handler.namespaces = () => [...namespaces]
+  for (const module of modules) register(module)
+  return handler
+}
+/**
+ * 把一次失败的信封翻译成调用方能展示的原因。
+ *
+ * `not_found` 是「浏览器半边比宿主半边新」的可观测症状：升级插件后客户端 bundle 由磁盘重新
+ * 加载，而宿主进程仍持有旧包，它没有新命名空间。此时重试永远不会成功，必须点名重启宿主。
+ * @param endpoint - 这次调用的 `<namespace>/<method>`。
+ * @param error - 宿主回传的失败原因，畸形信封下可能缺省。
+ * @returns 面向用户的失败描述。
+ */
+function describeSettingsFailure(endpoint: string, error: RpcResult<unknown>['error']): string {
+  if (error?.code === 'not_found') return `FTShare 设置接口 ${endpoint} 不存在：宿主插件还是升级前的版本，重启 DSH 后再试`
+  return `FTShare 设置操作失败（${error?.code ?? 'unknown'}）：${error?.message ?? '宿主未说明原因'}`
+}
+export async function callSettingsRpc<T>(transport: ClientTransport, namespace: string, method: string, payload: unknown = {}): Promise<T> {
+  const endpoint = `${namespace}/${method}`
+  const result = await transport.call(endpoint, payload)
+  if (!result.ok) throw new Error(describeSettingsFailure(endpoint, result.error))
+  return result.value as T
+}

package/src/core/shell.tsx

@@ -0,0 +1,81 @@
+import type { ReactNode } from 'react'
+import type { PropsRenderSlots, PropsRuntime, SlotCore, SlotMap } from '@deepseek-ai/dsh-client-ui-slots'
+// Type-only: pulls the `settings.section` SlotMap entry into this program.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import { FTSHARE_SETTINGS_CARD_SLOT, FTSHARE_SETTINGS_SECTION } from './contract.js'
+import { SETTINGS_CSS } from './styles.js'
+
+/** Section slot this seam contributes into; declared by the settings shell. */
+const FTSHARE_SETTINGS_SECTION_NAME = 'settings.section' as const
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface SlotMap {
+    /** One card inside the FTShare settings section; `order` sets its position. */
+    'ftshare.settings.card': {
+      kind: 'list'
+      scope: 'root'
+      owner: FtshareSettingsCardOwnerProps
+    }
+  }
+}
+/** Owner share of a card: the section supplies no card-specific props. */
+export interface FtshareSettingsCardOwnerProps {
+  /** Marker field: card owner props are intentionally empty. */
+  children?: never
+}
+/**
+ * The slice of the renderer-owned slots service this seam uses.
+ *
+ * `register` IS the ui-slots registration signature (the runtime registry
+ * reuses it verbatim, adding disposal through the caller's fiber); `inject`
+ * is the runtime wrapper's declaration-lifetime hook, which is why it is
+ * mirrored structurally here.
+ */
+export interface FtshareSettingsSlotsService {
+  readonly register: SlotCore['register']
+  /** Run `callback` for each declaration lifetime of `key`. */
+  inject(key: keyof SlotMap & string, callback: () => () => void): () => void
+}
+/**
+ * Browser context the section shell requires: the renderer's slots service.
+ * A card that needs more (its own services, invalidation events) declares the
+ * extra members on its own context type.
+ */
+export interface FtshareSettingsShellContext {
+  slots: FtshareSettingsSlotsService
+}
+/** Composed props of the section entry: the shell's owner share plus its declared child render. */
+export type FtshareSettingsSectionProps =
+  & PropsRuntime<typeof FTSHARE_SETTINGS_SECTION_NAME>
+  & PropsRenderSlots<typeof FTSHARE_SETTINGS_CARD_SLOT>
+
+/**
+ * The settings section shell: core CSS variables, the section chrome, and the
+ * single render site every card appears at. Cards own everything inside it.
+ */
+export function FtshareSettingsSection({ renderSlot }: FtshareSettingsSectionProps): ReactNode {
+  return <>
+    <style>{SETTINGS_CSS}</style>
+    {renderSlot(FTSHARE_SETTINGS_CARD_SLOT, {})}
+  </>
+}
+
+/**
+ * Declare the card slot and contribute the section that renders it.
+ *
+ * Declaring the child slot is what authorizes the render site; a card
+ * registering through {@link FTSHARE_SETTINGS_CARD_SLOT} before this runs waits
+ * for the declaration instead of failing.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the section and its declaration.
+ */
+export function registerSettingsSection(ctx: FtshareSettingsShellContext): () => void {
+  return ctx.slots.inject(FTSHARE_SETTINGS_SECTION_NAME, () => ctx.slots.register(
+    {
+      name: FTSHARE_SETTINGS_SECTION_NAME,
+      ...FTSHARE_SETTINGS_SECTION,
+      children: { [FTSHARE_SETTINGS_CARD_SLOT]: { kind: 'list', scope: 'root' } },
+    },
+    FtshareSettingsSection,
+  ))
+}

package/src/core/styles.ts

@@ -0,0 +1,43 @@
+/**
+ * The section shell's styles plus the theme tokens every card reads.
+ *
+ * The shell owns the container, typography, focus ring and link rules that
+ * every card sits inside; a card owns its own CSS and renders it from its own
+ * component, and core never styles card internals.
+ *
+ * The theme layer declares the plugin's `--ftshare-*` tokens once, on
+ * `.ftshare-settings` — the root element every card renders. Surfaces and text
+ * take their value from the host palette: `--dsw-alias-*` is what DSH
+ * publishes for the light, the dark and every registered theme, so one
+ * stylesheet follows the live palette with no script, no `prefers-color-scheme`
+ * copy and no second palette to keep in sync. The literal inside each `var()`
+ * is the fallback for a host that publishes no palette.
+ *
+ * The declarations sit on the card root rather than on `:root` because a
+ * custom property resolves where it is *declared*: `--dsw-alias-*` exists from
+ * `body` downwards, so a value derived from it above `body` would resolve to
+ * nothing and fall back. Consequence: the place to pin a look is the host
+ * palette itself (`ctx.theme.register` / `ctx.theme.overrideTokens`), not these
+ * names.
+ *
+ * `--ftshare-accent*` is the plugin's own brand and has no host equivalent. The
+ * values come from the FT brand layer's `--ft-*` tokens (`src/brand.ts`), with
+ * the same literal as the fallback so the card keeps its colors when that layer
+ * is absent. The fill and its ink are scheme-invariant;
+ * `--ftshare-accent-on-surface` mixes the same yellow towards the host's text
+ * colour, so the brand stays legible as the 11px eyebrow and as the focus ring
+ * on either surface.
+ */
+export const SETTINGS_CSS = `
+.ftshare-settings { --ftshare-text:var(--dsw-alias-label-primary,#f4f4f5); --ftshare-muted:var(--dsw-alias-label-secondary,#aeb2bd); --ftshare-panel:var(--dsw-alias-settings-card-fill,#292a30); --ftshare-border:var(--dsw-alias-settings-card-stroke,#44464f); --ftshare-control:var(--dsw-alias-border-l4,#696c77); --ftshare-input:var(--dsw-alias-bg-layer-1,#1d1e23); --ftshare-link:var(--dsw-alias-link,#d8c4fc); --ftshare-error:var(--dsw-alias-state-error-primary,#ffb5ad); --ftshare-accent:var(--ft-accent,#f0c433); --ftshare-accent-ink:var(--ft-accent-ink,#171717); --ftshare-accent-on-surface:color-mix(in srgb,var(--ftshare-accent) 50%,var(--dsw-alias-label-primary,#f4f4f5)); }
+.ftshare-settings { color:var(--ftshare-text); max-width:760px; font-size:14px; line-height:1.6; }
+.ftshare-settings * { box-sizing:border-box; }
+.ftshare-settings h2 { font-size:26px; margin:4px 0 8px; }
+.ftshare-settings h3 { font-size:15px; margin:0 0 12px; }
+.ftshare-settings p { margin:8px 0; color:var(--ftshare-muted); }
+.ftshare-settings header { display:flex; justify-content:space-between; align-items:flex-start; gap:20px; margin-bottom:20px; }
+.ftshare-settings small { display:block; color:var(--ftshare-muted); font-size:12px; margin:5px 0 12px; }
+.ftshare-settings :is(button,input,a):focus-visible { outline:2px solid var(--ftshare-accent-on-surface); outline-offset:3px; }
+.ftshare-settings a { color:var(--ftshare-link); }
+@media(max-width:540px) { .ftshare-settings header { flex-direction:column; gap:10px; } }
+`

package/src/core/transport.ts

@@ -0,0 +1,82 @@
+/**
+ * Host half of the settings transport.
+ *
+ * One exact route on the shared `/api` carrier: the carrier owns the Host/Origin
+ * fence and browser authentication, so this layer only decodes the call, bounds
+ * the body and returns the result envelope. Registering through
+ * `connection.rpc.handle` instead would read `webServer` through the context
+ * property proxy, whose resolution is ancestor-only and therefore fails for a
+ * plugin mounted beside the Web server.
+ */
+
+import { FTSHARE_SETTINGS_MAX_BODY_BYTES, FTSHARE_SETTINGS_ROUTE } from './contract.js'
+import type { RpcHandler, RpcResult, SettingsRoute } from './rpc-core.js'
+
+const invalidRequest = (): RpcResult<unknown> => ({
+  ok: false,
+  error: { code: 'bad_request', message: '请求参数不正确', details: {} },
+})
+
+/**
+ * Build the exact Fetch route served by the connection carrier.
+ * @param options - the settings call handler.
+ * @returns route definition ready for `connection.fetch.register`.
+ */
+export function createSettingsRoute({ handler }: { readonly handler: RpcHandler }): SettingsRoute {
+  return {
+    path: FTSHARE_SETTINGS_ROUTE,
+    methods: ['POST'],
+    requestBody: 'buffered',
+    fetch: async request => {
+      const body = await readJsonBody(request)
+      if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return json(400, invalidRequest())
+      }
+      const call = body as { readonly endpoint?: unknown; readonly payload?: unknown }
+      const endpoint = typeof call.endpoint === 'string' ? call.endpoint : ''
+      return json(200, await handler(endpoint, call.payload, request.signal))
+    },
+  }
+}
+
+/** Read and parse the JSON body; oversized, malformed or interrupted reads return undefined. */
+async function readJsonBody(request: Request): Promise<unknown> {
+  const reader = request.body?.getReader()
+  if (reader === undefined) return undefined
+  const chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      size += value.byteLength
+      if (size > FTSHARE_SETTINGS_MAX_BODY_BYTES) {
+        await reader.cancel()
+        return undefined
+      }
+      chunks.push(value)
+    }
+  } catch {
+    // A client-side abort only means this request lost its body; nothing else to read.
+    return undefined
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes))
+  } catch {
+    // A non-JSON body has the same single outcome: invalid request parameters.
+    return undefined
+  }
+}
+
+function json(status: number, payload: unknown): Response {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}