@stina/extension-api 0.58.0 → 1.3.1

package/src/schemas/contributions.schema.ts

@@ -176,6 +176,27 @@ export const PanelDefinitionSchema = z
   })
   .describe('Panel definition')
 
+/**
+ * A card for the strip above the conversation list.
+ *
+ * Deliberately the panel's component view rather than a profile of its own: a
+ * card and a panel are the same declarative idea at two sizes, and a second
+ * vocabulary would be a second thing to keep in step. `size` is what makes it a
+ * card, and it is checked rather than suggested because the sidebar is a few
+ * hundred pixels wide.
+ */
+export const StatusCardDefinitionSchema = z
+  .object({
+    id: z.string().describe('Unique card ID within the extension'),
+    title: z.string().describe('What it is called where the user picks it'),
+    icon: z.string().optional().describe('Icon name (from huge-icons)'),
+    size: z
+      .enum(['line', 'block'])
+      .describe('How much room it may take: one row, or up to three'),
+    view: PanelComponentViewSchema.describe('What it draws, and where the data comes from'),
+  })
+  .describe('Status card definition')
+
 // =============================================================================
 // Providers
 // =============================================================================
@@ -294,6 +315,10 @@ export const ExtensionContributionsSchema = z
   .object({
     toolSettings: z.array(ToolSettingsViewDefinitionSchema).optional().describe('Tool settings views'),
     panels: z.array(PanelDefinitionSchema).optional().describe('Right panel contributions'),
+    statusCards: z
+      .array(StatusCardDefinitionSchema)
+      .optional()
+      .describe('Cards for the strip above the conversation list'),
     providers: z.array(ProviderDefinitionSchema).optional().describe('AI providers'),
     tools: z.array(ToolDefinitionSchema).optional().describe('Tools for Stina to use'),
     commands: z.array(CommandDefinitionSchema).optional().describe('Slash commands'),
@@ -306,6 +331,7 @@ export const ExtensionContributionsSchema = z
 // Type Exports
 // =============================================================================
 
+export type StatusCardDefinition = z.infer<typeof StatusCardDefinitionSchema>
 export type LocalizedString = z.infer<typeof LocalizedStringSchema>
 export type ToolSettingsListMapping = z.infer<typeof ToolSettingsListMappingSchema>
 export type ToolSettingsActionDataSource = z.infer<typeof ToolSettingsActionDataSourceSchema>

package/src/schemas/index.ts

@@ -47,6 +47,7 @@ export {
   ToolSettingsListMappingSchema,
   ToolSettingsActionDataSourceSchema,
   PanelDefinitionSchema,
+  StatusCardDefinitionSchema,
   PanelViewSchema,
   PanelComponentViewSchema,
   PanelUnknownViewSchema,
@@ -67,6 +68,7 @@ export {
   type ToolSettingsListMapping,
   type ToolSettingsActionDataSource,
   type PanelDefinition,
+  type StatusCardDefinition,
   type PanelView,
   type PanelComponentView,
   type PanelUnknownView,
@@ -94,6 +96,7 @@ export {
   PanelActionSchema,
   HeaderPropsSchema,
   LabelPropsSchema,
+  ClockPropsSchema,
   ParagraphPropsSchema,
   ButtonPropsSchema,
   TextInputPropsSchema,
@@ -128,6 +131,9 @@ export {
   ChartPropsSchema,
   StatTrendSchema,
   StatTilePropsSchema,
+  ProgressShapeSchema,
+  ProgressColorSchema,
+  ProgressBarPropsSchema,
   KeyValueRowSchema,
   KeyValueListPropsSchema,
   TimelineVariantSchema,
@@ -150,6 +156,7 @@ export {
   type PanelAction,
   type HeaderProps,
   type LabelProps,
+  type ClockProps,
   type ParagraphProps,
   type ButtonProps,
   type TextInputProps,
@@ -181,8 +188,10 @@ export {
   ChatCardSchema,
   ChatCardComponentSchema,
   CHAT_CARD_COMPONENTS,
+  CHAT_CARD_PROPS,
   validateChatCard,
   describeChatCardProfile,
   type ChatCardComponent,
   type ChatCardValidation,
 } from './card.schema.js'
+

package/src/schemas/permissions.schema.ts

@@ -29,6 +29,7 @@ export const VALID_PERMISSIONS = [
   'settings.register',
   'commands.register',
   'panels.register',
+  'statusCards.register',
   'events.emit',
   'scheduler.register',
   'background.workers',
@@ -90,6 +91,7 @@ const CapabilityPermissionSchema = z
     'settings.register',
     'commands.register',
     'panels.register',
+    'statusCards.register',
     'events.emit',
     'scheduler.register',
     'chat.message.write',

package/src/types.components.ts

@@ -251,6 +251,19 @@ export interface LabelProps extends ExtensionComponentData {
   text: string
 }
 
+/**
+ * The extension API properties for the Clock component.
+ *
+ * The odd one out among the display components: it takes no facts, because the
+ * fact it shows is what time it is, and that is not something an action can
+ * hand over once. It reads the clock and the timezone from the host and keeps
+ * itself current, so a card carrying one stays right while the window is left
+ * open.
+ */
+export interface ClockProps extends ExtensionComponentData {
+  component: 'Clock'
+}
+
 /** The extension API properties for the paragraph component. */
 export interface ParagraphProps extends ExtensionComponentData {
   component: 'Paragraph'
@@ -731,6 +744,53 @@ export interface StatTileProps extends ExtensionComponentData {
   trendIsGood?: boolean
 }
 
+/** Whether a progress reading is drawn as a rail or as a ring. */
+export type ProgressShape = 'bar' | 'circle'
+
+/**
+ * The colours a progress reading may take.
+ *
+ * A closed list rather than a colour string: the caller is usually a language
+ * model, and the six names here are the six the themes actually define, so a
+ * reading cannot end up in a hue the current theme has no contrast for.
+ */
+export type ProgressColor = 'accent' | 'success' | 'warning' | 'danger' | 'info' | 'neutral'
+
+/**
+ * The extension API properties for the ProgressBar component.
+ *
+ * One value seen against the range it lives in — how far along something is,
+ * how loaded a day looks, how high a level sits. A StatTile says what the
+ * number *is*; this says where it *sits*, which is the thing a number alone
+ * cannot show.
+ *
+ * `min` and `max` are the range, not decoration: a value is drawn as its
+ * position between them, so "3 of 5" and "60 of 100" fill the same amount.
+ * Values outside the range are clamped rather than refused — a reading that
+ * ran past its ceiling should still draw as full.
+ */
+export interface ProgressBarProps extends ExtensionComponentData {
+  component: 'ProgressBar'
+  /** What is being measured, e.g. "Stressnivå". Shown beside the reading. */
+  label: string
+  value: number
+  /** Bottom of the range. Defaults to 0. */
+  min?: number
+  /** Top of the range. Defaults to 100. */
+  max?: number
+  /** Defaults to `bar`. */
+  shape?: ProgressShape
+  /** Defaults to `accent`. */
+  color?: ProgressColor
+  /** Written after the value, e.g. `%` or ` av 5`. */
+  unit?: string
+  /** The readout in words, when the bare number does not say it. Replaces value and unit. */
+  valueLabel?: string
+  /** One quiet line under the reading. */
+  caption?: string
+  icon?: HugeIconName
+}
+
 /** One row of a KeyValueList. */
 export interface KeyValueRow {
   label: string

package/src/types.contributions.ts

@@ -13,6 +13,8 @@ import type { ExtensionComponentData } from './types.components.js'
 export interface ExtensionContributions {
   /** Tool settings views for UI */
   toolSettings?: ToolSettingsViewDefinition[]
+  /** Cards for the strip above the conversation list */
+  statusCards?: StatusCardDefinition[]
   /** Right panel contributions */
   panels?: PanelDefinition[]
   /** AI providers */
@@ -170,6 +172,39 @@ export interface PanelDefinition {
   view: PanelView
 }
 
+/**
+ * A card for the strip above the conversation list.
+ *
+ * The same declarative machinery as a panel, in a much smaller space and with
+ * one rule that is not a style guide: a card says what is true right now. It
+ * has no controls, because a sidebar is read in passing and anything the user
+ * wants to do about what it says, they say in words.
+ *
+ * The user chooses which cards they want and in what order, so an extension
+ * offering three is offering three, not imposing them.
+ */
+export interface StatusCardDefinition {
+  /** Unique card ID within the extension */
+  id: string
+  /** What it is called where the user picks it */
+  title: string
+  /** Icon name (from huge-icons) */
+  icon?: string
+  /**
+   * How much room it may take.
+   *
+   * Part of the contract rather than a guideline, because the sidebar is a few
+   * hundred pixels wide and the first card written without a limit will be
+   * written against a screen.
+   *
+   * - `line`: one row. A figure, a label, a pill.
+   * - `block`: up to three rows.
+   */
+  size: 'line' | 'block'
+  /** What it draws, and where the data comes from */
+  view: PanelComponentView
+}
+
 /**
  * Panel view schema (declarative)
  */

package/src/types.permissions.ts

@@ -39,6 +39,7 @@ export type CapabilityPermission =
   | 'settings.register'
   | 'commands.register'
   | 'panels.register'
+  | 'statusCards.register'
   | 'events.emit'
   | 'scheduler.register'
   | 'chat.message.write'

package/src/types.tools.ts

@@ -73,6 +73,34 @@ export interface ToolResult {
    * would send her after a component that does not exist.
    */
   cardSuggestion?: string
+
+  /**
+   * Pictures to show the user, rendered in the conversation where the tool ran.
+   *
+   * For what a card cannot hold and the model cannot reproduce: a generated
+   * image, a rendered document, a photo fetched on the user's behalf. Like
+   * {@link ToolResult.display}, this is for the user only — it is lifted out
+   * before the result reaches the model, which would have nothing to do with
+   * the bytes but spend tokens on them. Say in `data` that a picture was shown,
+   * so she can talk about it without describing it back.
+   *
+   * The host stores each one as an attachment of the conversation, the same way
+   * a picture the user sends is stored, so it is served to every client and can
+   * be saved or shared from there. JPEG and PNG only, and 20 MB at most, since
+   * those are the limits the attachment store already holds users to. One that
+   * fails them is dropped with a warning rather than half-shown.
+   */
+  attachments?: ToolAttachment[]
+}
+
+/**
+ * One picture a tool wants shown. See {@link ToolResult.attachments}.
+ */
+export interface ToolAttachment {
+  /** The image bytes, base64 encoded. The format is read from the bytes. */
+  data: string
+  /** A file name to offer when the user saves it, e.g. `friday.png`. */
+  name?: string
 }
 
 /**

package/src/types.ts

@@ -31,6 +31,7 @@ export type {
   ToolSettingsActionDataSource,
   // Panels
   PanelDefinition,
+  StatusCardDefinition,
   PanelView,
   PanelUnknownView,
   PanelActionDataSource,
@@ -68,7 +69,7 @@ export type {
 } from './types.provider.js'
 
 // Tools and Actions
-export type { Tool, ToolResult, Action, ActionResult } from './types.tools.js'
+export type { Tool, ToolResult, ToolAttachment, Action, ActionResult } from './types.tools.js'
 
 // Context and APIs
 export type {