@openforge-app/plugin-sdk 0.1.0 → 0.2.4

package/dist/fileIcons.js

@@ -0,0 +1,84 @@
+export const DEFAULT_FILE_ICON = 'file';
+export const DEFAULT_FOLDER_ICON = 'folder';
+export const DEFAULT_FOLDER_OPEN_ICON = 'folder-open';
+// Lowercased extension (no leading dot) -> Material icon base name.
+// Only names that exist in vscode-material-icons/generated/icons are used.
+const EXTENSION_ICONS = {
+    ts: 'typescript', mts: 'typescript', cts: 'typescript',
+    tsx: 'react_ts',
+    js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+    jsx: 'react',
+    json: 'json', jsonc: 'json',
+    yaml: 'yaml', yml: 'yaml',
+    md: 'markdown', markdown: 'markdown', mdx: 'markdown',
+    css: 'css', less: 'css',
+    scss: 'sass', sass: 'sass',
+    html: 'html', htm: 'html',
+    svelte: 'svelte',
+    vue: 'vue',
+    rs: 'rust',
+    py: 'python',
+    rb: 'ruby',
+    go: 'go',
+    java: 'java',
+    kt: 'kotlin', kts: 'kotlin',
+    swift: 'swift',
+    c: 'c',
+    h: 'h', hpp: 'h', hh: 'h',
+    cc: 'cpp', cpp: 'cpp', cxx: 'cpp',
+    cs: 'csharp',
+    php: 'php',
+    sh: 'console', bash: 'console', zsh: 'console', fish: 'console',
+    sql: 'database',
+    graphql: 'graphql', gql: 'graphql',
+    xml: 'xml',
+    svg: 'svg',
+    png: 'image', jpg: 'image', jpeg: 'image', gif: 'image',
+    webp: 'image', bmp: 'image', ico: 'image', avif: 'image',
+    pdf: 'pdf',
+    zip: 'zip', tar: 'zip', gz: 'zip', tgz: 'zip', rar: 'zip', '7z': 'zip',
+    lock: 'lock',
+    toml: 'settings',
+    txt: 'document', log: 'document',
+    env: 'tune',
+};
+// Exact lowercased filename -> Material icon base name (takes precedence over extension).
+const FILENAME_ICONS = {
+    'package.json': 'nodejs',
+    'package-lock.json': 'lock',
+    'pnpm-lock.yaml': 'lock',
+    'yarn.lock': 'lock',
+    dockerfile: 'docker',
+    '.dockerignore': 'docker',
+    '.gitignore': 'git',
+    '.gitattributes': 'git',
+    '.gitmodules': 'git',
+    '.npmrc': 'npm',
+    '.npmignore': 'npm',
+};
+export function getFileIconName(filename) {
+    const base = (filename.split('/').pop() ?? filename).toLowerCase();
+    if (base in FILENAME_ICONS)
+        return FILENAME_ICONS[base];
+    if (base.endsWith('.d.ts'))
+        return 'typescript-def';
+    if (base === 'readme' || /^readme\.[^.]+$/.test(base))
+        return 'readme';
+    if (base === '.env' || base.startsWith('.env.'))
+        return 'tune';
+    const ext = base.includes('.') ? (base.split('.').pop() ?? '') : '';
+    return EXTENSION_ICONS[ext] ?? DEFAULT_FILE_ICON;
+}
+export function getFolderIconName(open) {
+    return open ? DEFAULT_FOLDER_OPEN_ICON : DEFAULT_FOLDER_ICON;
+}
+export const BUNDLED_ICON_NAMES = Object.freeze(Array.from(new Set([
+    DEFAULT_FILE_ICON,
+    DEFAULT_FOLDER_ICON,
+    DEFAULT_FOLDER_OPEN_ICON,
+    'typescript-def',
+    'readme',
+    'tune',
+    ...Object.values(EXTENSION_ICONS),
+    ...Object.values(FILENAME_ICONS),
+])).sort());

package/dist/frontend.d.ts

@@ -1,7 +1,10 @@
-import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendViewRegistry, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginStorageScope, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginViewProps, PluginViewRegistration } from './types';
+import type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState } from './browserSurfaces';
+import type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol } from './types';
 export declare const OPENFORGE_FRONTEND_PLUGIN_MARKER = "__openforgeFrontendPlugin";
 export type MarkedFrontendPlugin<TPlugin extends FrontendPlugin = FrontendPlugin> = TPlugin & {
     readonly [OPENFORGE_FRONTEND_PLUGIN_MARKER]: true;
 };
 export declare function defineFrontendPlugin<const TPlugin extends FrontendPlugin>(plugin: TPlugin): MarkedFrontendPlugin<TPlugin>;
-export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendViewRegistry, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginStorageScope, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginViewProps, PluginViewRegistration, };
+export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
+export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState, };
+export type { CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, Disposable, FrontendBackendBridge, FrontendOpenForgeAPI, FrontendPlugin, FrontendPluginContext, FrontendSettingsRegistry, FrontendTaskPaneRegistry, FrontendInjectionPointRegistry, FrontendTaskStartRegistry, FrontendTaskUIRegistry, FrontendViewRegistry, InjectionPointLocation, NavigationAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginInjectionPointRegistration, PluginSettingsSectionProps, PluginSettingsSectionRegistration, PluginSettingsSectionScope, PluginStorageScope, PluginSvgIcon, PluginTaskPaneProps, PluginTaskPaneTabRegistration, PluginTaskUISectionProps, PluginTaskUISectionRegistration, PluginViewProps, PluginViewRegistration, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, PtyBufferState, TerminalImageProtocol, };

package/dist/frontend.js

@@ -7,3 +7,4 @@ export function defineFrontendPlugin(plugin) {
     });
     return plugin;
 }
+export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
+export type { BrowserSurfaceCapture, BrowserSurfaceFeedbackSelection, BrowserSurfaceVisualFeedback, BrowserSurfaceRegion, BrowserSurfaceErrorCode, BrowserSurfaceNavigationError, BrowserSurfacesAPI, GetOrCreateBrowserSurfaceRequest, TaskBrowserSurfaceController, TaskBrowserSurfaceState, } from './browserSurfaces';
 export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
 export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
-export { MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
-export type { AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, FileSystemAPI, ImplementationRun, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginSettingsSectionProps, PluginState, PluginTaskPaneProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, ShellAPI, ShellResizeRequest, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, StartTaskImplementationRequest, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TasksAPI, ValidationError, } from './types';
-export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingViewContribution, } from './testing';
+export { TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
+export type { AgentCommandDescriptor, AgentCommandMetadata, AgentCommandRuntime, AttentionAPI, BackendReadyState, CommandDescriptor, CommandRegistry, CommandRegistration, CommandShortcutMetadata, ComposeTaskRequest, ComposeTaskResult, ConfigureStartPromptContributionRequest, CreateTaskRequest, Disposable, BackendFileSystemAPI, ExternalReadDirectoryRequest, ExternalReadFileRequest, ExternalReadFileSystemAPI, FileSystemAPI, UserDataDirectoryRequest, UserDataFileRequest, UserDataFileSystemAPI, UserDataFileWriteRequest, ImplementationRun, InjectionPointLocation, JsonObject, JsonPrimitive, JsonSchema, JsonValue, MaybePromise, KeyValueConfigAPI, NotificationRequest, NavigationAPI, NotificationsAPI, OpenForgeCommonAPI, OpenForgeContextSnapshot, OpenForgeNavigationRequest, OpenForgeNavigationSnapshot, OpenForgePackageMetadata, OpenForgePluginCapability, OpenForgePluginContext, OpenForgePluginPackageJson, PluginCommandInvocationContext, PluginCommandInvocationSource, PluginComponentLoader, PluginComponentModule, PluginEntry, PluginIcon, PluginSidebarNavigationProps, PluginSidebarViewIdentity, PluginInjectionPointProps, PluginSettingsSectionProps, PluginState, PluginSvgIcon, PluginTaskPaneProps, PluginTaskUISectionProps, PluginViewProps, PluginStorage, PluginStorageScope, PluginViewKey, ProjectsAPI, PtyBufferState, ShellAPI, ShellResizeRequest, TaskStartPrefixContext, TaskStartPrefixProviderRegistration, TerminalImageProtocol, ShellSessionRequest, ShellSpawnRequest, ShellWriteRequest, StartPromptContribution, SendTaskFollowUpRequest, StartTaskImplementationRequest, TaskFollowUpDisposition, TaskFollowUpErrorCode, TaskFollowUpReceipt, SubscriptionSink, SupportedOpenForgeApiVersion, SystemAPI, TaskLinkHandler, TaskLinkHandlerResult, TaskLinkOpenRequest, TaskLinksAPI, TasksAPI, ValidationError, } from './types';
+export type { MockBackendOpenForgeAPI, MockFrontendOpenForgeAPI, TestingBackgroundServiceContribution, TestingBackendMethodContribution, TestingCommandContribution, TestingContributionBase, TestingEventListenerContribution, TestingOpenForgeApiCalls, TestingOpenForgeApiOptions, TestingOpenForgeRegistrySnapshot, TestingRuntimeKind, TestingRuntimeScope, TestingSettingsSectionContribution, TestingTaskPaneTabContribution, TestingTaskUISectionContribution, TestingViewContribution, } from './testing';
 export { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';
 export type { ProjectFileTreeEntry, ProjectFileTreeItemAccessibility, ProjectFileTreeKeyboardAction, ProjectFileTreeNode, } from './projectFileTree';

package/dist/index.js

@@ -1,6 +1,7 @@
+export { BrowserSurfaceError, isAllowedBrowserSurfaceUrl } from './browserSurfaces';
 export { OPENFORGE_PACKAGE_METADATA_SCHEMA, OPENFORGE_PLUGIN_CAPABILITIES, isOpenForgePackageMetadata, isPluginPackageMetadata, isSupportedOpenForgeApiVersion, validateOpenForgePackageMetadata, validatePluginPackageMetadata, } from './manifest';
 export { createMemoryPluginStorage, createMockBackendOpenForgeApi, createMockFrontendOpenForgeApi, createMockOpenForgeApi, createMockPluginContext, createOpenForgeRegistryFake, createTestingCalls, TestingOpenForgeRegistryFake, TestingSubscriptionSink, } from './testing';
-export { MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
+export { TaskFollowUpError, MAX_SUPPORTED_API_VERSION, MIN_SUPPORTED_API_VERSION, OPENFORGE_PLUGIN_API_VERSION, SUPPORTED_OPENFORGE_API_VERSIONS, isPluginViewKey, makePluginViewKey, parsePluginViewKey, } from './types';
 export { parseStrictFiniteNumber } from './numberParsing';
 export { buildProjectFileTree, flattenVisibleProjectFileTree, formatProjectFileTreeSize, getProjectFileTreeDepth, getProjectFileTreeItemAccessibility, getProjectFileTreeKeyboardAction, getProjectFileTreeParentPath, hasProjectFileTreeShortcutModifier, projectFileTreePathToId, } from './projectFileTree';
 export { canMergePullRequest, getMergeReadiness, hasMergeConflicts, isClosedUnmergedPullRequest, isMergedPullRequest, isQueuedForMerge, isReadyToMerge, parseCheckRuns, preservePullRequestState, splitCheckRuns, } from './domain';

package/dist/manifest.d.ts

@@ -8,6 +8,46 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
     type: string;
     additionalProperties: boolean;
     required: string[];
+    dependentRequired: {
+        frontendStyles: string[];
+    };
+    allOf: ({
+        if: {
+            properties: {
+                requires: {
+                    contains: {
+                        const: string;
+                    };
+                };
+                enablement?: undefined;
+            };
+            required: string[];
+        };
+        then: {
+            required: string[];
+            properties?: undefined;
+        };
+    } | {
+        if: {
+            properties: {
+                enablement: {
+                    const: string;
+                };
+                requires?: undefined;
+            };
+            required: string[];
+        };
+        then: {
+            properties: {
+                requires: {
+                    contains: {
+                        const: string;
+                    };
+                };
+            };
+            required: string[];
+        };
+    })[];
     properties: {
         id: {
             type: string;
@@ -26,9 +66,36 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
             type: string;
             minLength: number;
         };
+        enablement: {
+            enum: string[];
+            default: string;
+            description: string;
+        };
         icon: {
-            type: string;
-            minLength: number;
+            oneOf: ({
+                type: string;
+                minLength: number;
+                pattern: string;
+                additionalProperties?: undefined;
+                required?: undefined;
+                properties?: undefined;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    svg: {
+                        type: string;
+                        minLength: number;
+                        pattern: string;
+                    };
+                };
+                minLength?: undefined;
+                pattern?: undefined;
+            })[];
             description: string;
         };
         frontend: {
@@ -36,6 +103,17 @@ export declare const OPENFORGE_PACKAGE_METADATA_SCHEMA: {
             minLength: number;
             description: string;
         };
+        frontendStyles: {
+            type: string;
+            minItems: number;
+            uniqueItems: boolean;
+            items: {
+                type: string;
+                minLength: number;
+                pattern: string;
+            };
+            description: string;
+        };
         backend: {
             type: string;
             minLength: number;

package/dist/manifest.js

@@ -1,4 +1,5 @@
 import packageMetadataSchemaData from './openforgePackageMetadataSchema.json';
+import { isPluginIconName, isPluginSvgIcon } from './pluginIconContract';
 import { SUPPORTED_OPENFORGE_API_VERSIONS } from './types';
 export const OPENFORGE_PACKAGE_METADATA_SCHEMA = packageMetadataSchemaData;
 export const OPENFORGE_PLUGIN_CAPABILITIES = packageMetadataSchemaData.properties.requires.items.enum;
@@ -27,6 +28,45 @@ function validateOptionalString(value, path) {
     }
     return [];
 }
+function validateEnablement(value) {
+    if (value === undefined || value === 'app' || value === 'project') {
+        return [];
+    }
+    return [{ path: 'enablement', message: 'Must be "app" or "project"' }];
+}
+function validatePluginIcon(value) {
+    if (value === undefined || isPluginIconName(value) || isPluginSvgIcon(value)) {
+        return [];
+    }
+    return [{ path: 'icon', message: 'Must be a non-empty Lucide icon name or { type: "svg", svg }' }];
+}
+function validateFrontendStyles(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        return [{ path: 'frontendStyles', message: 'Must be an array' }];
+    }
+    const errors = [];
+    if (value.length === 0) {
+        errors.push({ path: 'frontendStyles', message: 'Must contain at least one stylesheet path' });
+    }
+    const seen = new Set();
+    value.forEach((item, index) => {
+        if (!isNonEmptyString(item)) {
+            errors.push({ path: `frontendStyles[${index}]`, message: 'Must be a non-empty string' });
+        }
+        else if (!item.endsWith('.css')) {
+            errors.push({ path: `frontendStyles[${index}]`, message: 'Must point to a built CSS artifact' });
+        }
+        else if (seen.has(item)) {
+            errors.push({ path: `frontendStyles[${index}]`, message: 'Duplicate stylesheet path' });
+        }
+        else {
+            seen.add(item);
+        }
+    });
+    return errors;
+}
 export function isSupportedOpenForgeApiVersion(apiVersion) {
     return typeof apiVersion === 'number'
         && Number.isInteger(apiVersion)
@@ -70,10 +110,24 @@ export function validateOpenForgePackageMetadata(data) {
     errors.push(...validateApiVersion(data.apiVersion));
     errors.push(...validateRequiredString(data.displayName, 'displayName'));
     errors.push(...validateRequiredString(data.description, 'description'));
-    errors.push(...validateOptionalString(data.icon, 'icon'));
+    errors.push(...validateEnablement(data.enablement));
+    errors.push(...validatePluginIcon(data.icon));
     errors.push(...validateOptionalString(data.frontend, 'frontend'));
+    errors.push(...validateFrontendStyles(data.frontendStyles));
+    if (data.frontendStyles !== undefined && !isNonEmptyString(data.frontend)) {
+        errors.push({ path: 'frontendStyles', message: 'Requires a frontend entry' });
+    }
     errors.push(...validateOptionalString(data.backend, 'backend'));
     errors.push(...validateRequires(data.requires));
+    if (data.enablement === 'app' && (!Array.isArray(data.requires) || !data.requires.includes('appEnablement'))) {
+        errors.push({ path: 'requires', message: 'App enablement requires the appEnablement capability' });
+    }
+    if (Array.isArray(data.requires) && data.requires.includes('browserSurfaces') && !isNonEmptyString(data.frontend)) {
+        errors.push({ path: 'requires', message: 'browserSurfaces capability requires a frontend entry' });
+    }
+    if (Array.isArray(data.requires) && data.requires.includes('taskLinks') && !isNonEmptyString(data.frontend)) {
+        errors.push({ path: 'requires', message: 'taskLinks capability requires a frontend entry' });
+    }
     if (data.contributes !== undefined) {
         errors.push({ path: 'contributes', message: 'Manifest contribution arrays are not supported; register contributions at runtime' });
     }

package/dist/markdown.d.ts

@@ -1,5 +1,9 @@
 export interface RenderMarkdownOptions {
     imageBaseUrl?: string | null;
+    markdownFilePath?: string | null;
+    deferRepositoryImages?: boolean;
 }
-export declare function resolveMarkdownImageSrc(src: string | null, imageBaseUrl: string | null | undefined): string | null;
+export declare function resolveMarkdownRepositoryPath(value: string | null, markdownFilePath: string): string | null;
+export declare function getMarkdownRepositoryLinkSuffix(value: string): string;
+export declare function resolveMarkdownImageSrc(src: string | null, imageBaseUrl: string | null | undefined, markdownFilePath?: string): string | null;
 export declare function renderMarkdownHtml(content: string, options?: RenderMarkdownOptions): string;

package/dist/markdown.js

@@ -1,7 +1,5 @@
 import { marked } from 'marked';
 import { sanitizeHtml } from './sanitize';
-const RELATIVE_PARENT_SEGMENT = /^\.\.\//;
-const RELATIVE_CURRENT_SEGMENT = /^\.\//;
 const markedOptions = {
     gfm: true,
     breaks: true,
@@ -9,39 +7,90 @@ const markedOptions = {
 function hasAbsoluteOrSpecialUrl(value) {
     return /^[a-z][a-z\d+.-]*:/i.test(value) || value.startsWith('//') || value.startsWith('#');
 }
-function normalizeRepoRelativeImagePath(value) {
-    let normalized = value.startsWith('/') ? value.slice(1) : value;
-    while (RELATIVE_CURRENT_SEGMENT.test(normalized)) {
-        normalized = normalized.replace(RELATIVE_CURRENT_SEGMENT, '');
+function decodeMarkdownPath(value) {
+    try {
+        return decodeURI(value);
     }
-    while (RELATIVE_PARENT_SEGMENT.test(normalized)) {
-        normalized = normalized.replace(RELATIVE_PARENT_SEGMENT, '');
+    catch {
+        return value;
     }
-    return normalized;
+}
+function splitMarkdownRepositoryReference(value) {
+    const suffixIndex = value.search(/[?#]/);
+    return suffixIndex < 0
+        ? { pathValue: value, suffix: '' }
+        : { pathValue: value.slice(0, suffixIndex), suffix: value.slice(suffixIndex) };
+}
+export function resolveMarkdownRepositoryPath(value, markdownFilePath) {
+    if (!value)
+        return null;
+    const trimmedValue = value.trim();
+    if (!trimmedValue || hasAbsoluteOrSpecialUrl(trimmedValue))
+        return null;
+    const { pathValue } = splitMarkdownRepositoryReference(trimmedValue);
+    if (!pathValue)
+        return null;
+    const repositoryPath = decodeMarkdownPath(pathValue);
+    if (repositoryPath.includes('\\'))
+        return null;
+    const markdownDirectory = markdownFilePath.split('/').slice(0, -1).join('/');
+    const candidate = repositoryPath.startsWith('/')
+        ? repositoryPath.slice(1)
+        : [markdownDirectory, repositoryPath].filter(Boolean).join('/');
+    const parts = [];
+    for (const segment of candidate.split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (parts.length === 0)
+                return null;
+            parts.pop();
+        }
+        else {
+            parts.push(segment);
+        }
+    }
+    return parts.length > 0 ? parts.join('/') : null;
+}
+export function getMarkdownRepositoryLinkSuffix(value) {
+    return splitMarkdownRepositoryReference(value.trim()).suffix;
 }
 function withTrailingSlash(value) {
     return value.endsWith('/') ? value : `${value}/`;
 }
-export function resolveMarkdownImageSrc(src, imageBaseUrl) {
-    if (!src || !imageBaseUrl)
+export function resolveMarkdownImageSrc(src, imageBaseUrl, markdownFilePath = '') {
+    if (!imageBaseUrl)
         return null;
-    const trimmedSrc = src.trim();
-    if (!trimmedSrc || hasAbsoluteOrSpecialUrl(trimmedSrc))
+    const repositoryPath = resolveMarkdownRepositoryPath(src, markdownFilePath);
+    if (!repositoryPath)
         return null;
     try {
-        return new URL(normalizeRepoRelativeImagePath(trimmedSrc), withTrailingSlash(imageBaseUrl)).href;
+        return new URL(repositoryPath, withTrailingSlash(imageBaseUrl)).href;
     }
     catch {
         return null;
     }
 }
-function resolveMarkdownImageSources(html, imageBaseUrl) {
-    if (!imageBaseUrl || typeof document === 'undefined')
+function prepareMarkdownImageSources(html, options) {
+    if (typeof document === 'undefined' || (!options.imageBaseUrl && !options.deferRepositoryImages))
         return html;
     const template = document.createElement('template');
     template.innerHTML = html;
     for (const image of template.content.querySelectorAll('img[src]')) {
-        const resolvedSrc = resolveMarkdownImageSrc(image.getAttribute('src'), imageBaseUrl);
+        const source = image.getAttribute('src')?.trim() ?? '';
+        const shouldDefer = options.deferRepositoryImages && source.length > 0 && !hasAbsoluteOrSpecialUrl(source);
+        if (shouldDefer) {
+            image.removeAttribute('src');
+            const repositoryPath = resolveMarkdownRepositoryPath(source, options.markdownFilePath ?? '');
+            if (repositoryPath) {
+                image.setAttribute('data-markdown-repository-path', repositoryPath);
+            }
+            continue;
+        }
+        const repositoryPath = resolveMarkdownRepositoryPath(source, options.markdownFilePath ?? '');
+        if (!repositoryPath)
+            continue;
+        const resolvedSrc = resolveMarkdownImageSrc(repositoryPath, options.imageBaseUrl);
         if (resolvedSrc) {
             image.setAttribute('src', resolvedSrc);
         }
@@ -50,5 +99,5 @@ function resolveMarkdownImageSources(html, imageBaseUrl) {
 }
 export function renderMarkdownHtml(content, options = {}) {
     const rawHtml = marked.parse(content, markedOptions);
-    return sanitizeHtml(resolveMarkdownImageSources(rawHtml, options.imageBaseUrl));
+    return sanitizeHtml(prepareMarkdownImageSources(rawHtml, options));
 }

package/dist/openforgePackageMetadataSchema.json

@@ -6,6 +6,41 @@
     "type": "object",
     "additionalProperties": false,
     "required": ["id", "apiVersion", "displayName", "description"],
+    "dependentRequired": {
+        "frontendStyles": ["frontend"]
+    },
+    "allOf": [
+        {
+            "if": {
+                "properties": {
+                    "requires": { "contains": { "const": "browserSurfaces" } }
+                },
+                "required": ["requires"]
+            },
+            "then": { "required": ["frontend"] }
+        },
+        {
+            "if": {
+                "properties": {
+                    "requires": { "contains": { "const": "taskLinks" } }
+                },
+                "required": ["requires"]
+            },
+            "then": { "required": ["frontend"] }
+        },
+        {
+            "if": {
+                "properties": { "enablement": { "const": "app" } },
+                "required": ["enablement"]
+            },
+            "then": {
+                "properties": {
+                    "requires": { "contains": { "const": "appEnablement" } }
+                },
+                "required": ["requires"]
+            }
+        }
+    ],
     "properties": {
         "id": {
             "type": "string",
@@ -24,16 +59,50 @@
             "type": "string",
             "minLength": 1
         },
+        "enablement": {
+            "enum": ["app", "project"],
+            "default": "project",
+            "description": "Lifecycle ownership for this plugin package. Omission means project-owned enablement."
+        },
         "icon": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Semantic OpenForge icon key or package asset reference."
+            "oneOf": [
+                {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S"
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "svg"],
+                    "properties": {
+                        "type": { "const": "svg" },
+                        "svg": {
+                            "type": "string",
+                            "minLength": 1,
+                            "pattern": "\\S"
+                        }
+                    }
+                }
+            ],
+            "description": "Lucide icon name in kebab-case or inline SVG geometry using the PluginIcon contract."
         },
         "frontend": {
             "type": "string",
             "minLength": 1,
             "description": "Path to the built frontend JavaScript entry artifact."
         },
+        "frontendStyles": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\.css$"
+            },
+            "description": "Paths to built frontend CSS artifacts. The renderer attaches them before importing the frontend entry and removes them when the plugin deactivates."
+        },
         "backend": {
             "type": "string",
             "minLength": 1,
@@ -47,7 +116,9 @@
                     "commands",
                     "events",
                     "views",
+                    "injectionPoints",
                     "taskPane",
+                    "taskStart",
                     "settings",
                     "background",
                     "backend",
@@ -61,8 +132,13 @@
                     "notifications",
                     "attention",
                     "system.openUrl",
+                    "system.writeClipboardText",
                     "config",
-                    "projectConfig"
+                    "projectConfig",
+                    "browserSurfaces",
+                    "taskLinks",
+                    "appEnablement",
+                    "customSidebarNavigation"
                 ]
             }
         }

package/dist/pluginIconContract.d.ts

@@ -0,0 +1,3 @@
+import type { PluginSvgIcon } from './types';
+export declare function isPluginIconName(value: unknown): value is string;
+export declare function isPluginSvgIcon(value: unknown): value is PluginSvgIcon;

package/dist/pluginIconContract.js

@@ -0,0 +1,12 @@
+export function isPluginIconName(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function isPluginSvgIcon(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const icon = value;
+    return Object.keys(icon).length === 2
+        && icon.type === 'svg'
+        && typeof icon.svg === 'string'
+        && icon.svg.trim().length > 0;
+}

package/dist/pluginIcons.d.ts

@@ -0,0 +1,7 @@
+import type { PluginIcon } from './types';
+export declare const MAX_PLUGIN_SVG_ICON_CHARACTERS = 10000;
+/**
+ * Validates and sanitizes a plugin icon before it crosses a host contribution boundary.
+ * Named icons are preserved so unsupported names can retain the host's existing fallback.
+ */
+export declare function sanitizePluginIcon(icon: unknown): PluginIcon;