@deepseek-ai/dsh-experimental-client-ui-forge 0.0.0-stage → 0.2.2-alpha.3

package/lib/types/client/WorktreeToggle.d.ts

@@ -0,0 +1,43 @@
+/** New Session option: start the Session in a new worktree, from a chosen local branch. */
+import { type ReactNode } from 'react';
+import type { HostObservable, InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ForgeBranches } from '../types.ts';
+import type { NS } from './locales.ts';
+import type { PanelSnapshot } from './source.ts';
+/** Business face of the New Session option. */
+export interface WorktreeToggleInjected {
+    /** Panel snapshot of the Session; the renderer binds it as `usePanel`. */
+    readonly hooks: {
+        readonly panel: HostObservable<PanelSnapshot>;
+    };
+    /**
+     * Request a worktree from a base branch, replacing an open request.
+     * @param from - base branch, or null for HEAD.
+     * @returns whether the Host accepted it.
+     */
+    readonly request: (from: string | null) => Promise<boolean>;
+    /**
+     * Withdraw the open request.
+     * @returns whether the Host accepted it.
+     */
+    readonly cancel: () => Promise<boolean>;
+    /**
+     * List the local branches of the Session's checkout.
+     * @returns the branches, or undefined when they could not be read.
+     */
+    readonly branches: () => Promise<ForgeBranches | undefined>;
+}
+/** Full props of the New Session option. */
+export type WorktreeToggleProps = InjectFace<WorktreeToggleInjected> & PropsLocale<typeof NS>;
+/**
+ * Render the worktree option while the Session can still start in a worktree:
+ * the current branch, or the base branch menu once requested, then the checkbox.
+ * A blocked request keeps its selected base visible without a menu; the checkbox
+ * only withdraws it. Branch details support pointer, touch, and keyboard access.
+ * The request stays fixed while the worktree is being created.
+ * @param props - panel snapshot hook, request actions, and copy.
+ * @returns the option, or nothing outside a known Git checkout, once a turn started,
+ * the request settled, or no worktree service is mounted.
+ */
+export declare function WorktreeToggle({ usePanel, request, cancel, branches, t }: WorktreeToggleProps): ReactNode;
+//# sourceMappingURL=WorktreeToggle.d.ts.map

package/lib/types/client/changes-address.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The changes view's tab type: the right-Sidebar view of one Session's local
+ * changes or of one change request bound to it. Its addresses name the Session
+ * and the source, `dsh-resource://forge-changes/<session>/local` or
+ * `dsh-resource://forge-changes/<session>/change/<url>`, each part
+ * percent-encoded; the source names the tab.
+ */
+import type { SidebarRightTabDefinition } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { NS } from './locales.ts';
+/** Kind of the changes tab. */
+export declare const CHANGES_KIND = "forge-changes";
+/** Registry id of the changes tab type, also the key its body and title register under. */
+export declare const CHANGES_ID = "@deepseek-ai/dsh-experimental-client-ui-forge/changes";
+/** What a changes view shows. */
+export type ChangesSource = 
+/** The changes of the Session's checkout. */
+{
+    readonly kind: 'local';
+}
+/** The changes of one change request bound to the Session, by its binding URL. */
+ | {
+    readonly kind: 'change';
+    readonly url: string;
+};
+/** The Session and the source one address names. */
+export interface ChangesTarget {
+    /** Session whose checkout or binding the view reads. */
+    readonly sessionId: SessionId;
+    /** What the view shows. */
+    readonly source: ChangesSource;
+}
+/** Navigation parameters of a changes tab. */
+export interface ChangesParams {
+    /** File to scroll to, by its path in the diff. */
+    readonly path?: string;
+}
+declare module '@deepseek-ai/dsh-client-ui-sidebar-right/client' {
+    interface SidebarRightResourceParamsMap {
+        /** The file a changes tab scrolls to. */
+        'forge-changes': ChangesParams;
+    }
+}
+/**
+ * Mint the address of a changes view.
+ * @param target - Session and source.
+ * @returns the `dsh-resource://forge-changes/…` address.
+ */
+export declare function changesAddress(target: ChangesTarget): string;
+/**
+ * Read the Session and source back out of a changes address.
+ * @param address - a resource address.
+ * @returns the target, or undefined for an address this package did not mint.
+ */
+export declare function parseChangesAddress(address: string): ChangesTarget | undefined;
+/**
+ * Name a changes view: 本地变更 for the local changes, #N 的变更 for a change request with a number.
+ * @param source - what the view shows.
+ * @param t - forge panel copy.
+ * @returns the title in the current language.
+ */
+export declare function changesTitle(source: ChangesSource, t: TranslateNS<typeof NS>): string;
+/**
+ * The changes type's registry definition.
+ * @param t - forge panel copy, read on every title call.
+ * @returns the definition to register.
+ */
+export declare function changesDefinition(t: TranslateNS<typeof NS>): SidebarRightTabDefinition;
+//# sourceMappingURL=changes-address.d.ts.map

package/lib/types/client/changes-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Choices of each changes tab: the local scope, the side-by-side view, line
+ * wrapping, and the navigation it last applied. One bucket per tab, so two
+ * views in one Session keep their own choices; the bucket ends with the tab
+ * record's signal.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
+import type { ForgeLocalScope } from '../types.ts';
+/** One changes tab's choices. */
+export interface ChangesTabState {
+    /** Local changes shown; a change request view ignores it. */
+    scope: ForgeLocalScope['kind'];
+    /** Whether deletions and additions show in two columns. */
+    split: boolean;
+    /** Whether long lines wrap instead of being cut at the column edge. */
+    wrap: boolean;
+    /** The navigation revision last applied, whose file the view scrolled to. */
+    navigated: number;
+}
+/** Every changes tab's choices, keyed by tab id. */
+export interface ChangesState {
+    byTab: Record<string, ChangesTabState>;
+}
+/** The changes store's write set; every action names the tab it writes. */
+type ChangesActions = {
+    navigated: (draft: ChangesState, tabId: string, revision: number) => void;
+    scoped: (draft: ChangesState, tabId: string, scope: ForgeLocalScope['kind']) => void;
+    toggledSplit: (draft: ChangesState, tabId: string) => void;
+    toggledWrap: (draft: ChangesState, tabId: string) => void;
+    forget: (draft: ChangesState, tabId: string) => void;
+};
+/**
+ * Declare the changes tab's store; the registration declares it as an
+ * exclusive store, so the framework mints one instance per Session.
+ * @returns the store handle to declare on the registration.
+ */
+export declare function createChangesStore(): EngineStoreHandle<ChangesState, ChangesActions>;
+export {};
+//# sourceMappingURL=changes-store.d.ts.map

package/lib/types/client/checkout.d.ts

@@ -0,0 +1,34 @@
+/** What the panel's checkout row says about the checkout the Session works in. */
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ForgePanelState } from '../types.ts';
+import type { NS } from './locales.ts';
+type Translate = PropsLocale<typeof NS>['t'];
+/** Facts the checkout row shows. */
+export interface CheckoutLabel {
+    /** Branch name, the abbreviated commit while HEAD is detached, or null when HEAD has no commit. */
+    readonly name: string | null;
+    /** Whether HEAD is detached. */
+    readonly detached: boolean;
+    /** Kind of directory: a worktree with its base, another worktree, the project directory, or a removed worktree. */
+    readonly kind: string;
+    /** The kind with the directory path, home abbreviated to `~`. */
+    readonly tooltip: string;
+    /** Whether the worktree the Session works in is gone. */
+    readonly missing: boolean;
+    /** Full path of the directory, home not abbreviated; a removed worktree keeps the path it was created at. */
+    readonly path: string;
+    /** Whether the directory is a worktree rather than the project directory. */
+    readonly worktree: boolean;
+}
+/**
+ * Describe the checkout of a Session. A worktree this panel created names its
+ * base; any other linked worktree is a worktree, and the main checkout is the
+ * project directory. A removed worktree keeps its branch name.
+ * @param state - panel state.
+ * @param home - Host account home, or undefined to show full paths.
+ * @param t - forge panel copy.
+ * @returns the label, or undefined before a successful inspection.
+ */
+export declare function checkoutLabel(state: ForgePanelState, home: string | undefined, t: Translate): CheckoutLabel | undefined;
+export {};
+//# sourceMappingURL=checkout.d.ts.map

package/lib/types/client/code-selection.d.ts

@@ -0,0 +1,23 @@
+/** Read browser text selections from one diff side without including the interleaved opposite column. */
+/** Selected displayed lines and the exact selected text on their side. */
+export interface CodeSelection {
+    readonly side: 'L' | 'R';
+    readonly from: number;
+    readonly to: number;
+    readonly text: string;
+}
+/**
+ * Find the side where a text selection begins; unified context belongs to the new side.
+ * @param root - this file's diff element.
+ * @param node - pointer or selection anchor.
+ * @returns the available side, or undefined outside code text.
+ */
+export declare function codeSideAt(root: HTMLElement, node: Node | null): 'L' | 'R' | undefined;
+/**
+ * Read only code fragments from the selected side, retaining partial first and last lines for copy.
+ * @param root - this file's diff element.
+ * @param side - side captured when the gesture began.
+ * @returns the selected range and text, or undefined for collapsed or cross-file selections.
+ */
+export declare function readCodeSelection(root: HTMLElement, side: 'L' | 'R'): CodeSelection | undefined;
+//# sourceMappingURL=code-selection.d.ts.map

package/lib/types/client/diff-rows.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Drawn rows of one file diff: numbered patch lines, their side-by-side
+ * pairing, and the unchanged lines between hunks, which stay collapsed until
+ * the file's new side supplies them.
+ */
+import type { ForgeDiffFile, ForgeDiffHunk } from '../types.ts';
+/** One drawn line with its number on each side that has it. */
+export type DiffRow = {
+    readonly kind: 'add';
+    readonly old: null;
+    readonly new: number;
+    readonly text: string;
+} | {
+    readonly kind: 'del';
+    readonly old: number;
+    readonly new: null;
+    readonly text: string;
+} | {
+    readonly kind: 'context';
+    readonly old: number;
+    readonly new: number;
+    readonly text: string;
+};
+/** One side of a side-by-side row. */
+export interface SplitCell {
+    readonly kind: DiffRow['kind'];
+    readonly no: number;
+    readonly text: string;
+}
+/** One side-by-side row; a side without a line is null. */
+export interface SplitRow {
+    readonly left: SplitCell | null;
+    readonly right: SplitCell | null;
+}
+/** A run of drawn rows, or unchanged lines drawn as one row that expands them. */
+export type DiffSegment = {
+    readonly kind: 'rows';
+    readonly rows: readonly DiffRow[];
+}
+/**
+ * `index` is the hunk the lines precede, or the hunk count for the lines after the last hunk;
+ * `count` is null while the length of the file is unknown.
+ */
+ | {
+    readonly kind: 'gap';
+    readonly index: number;
+    readonly count: number | null;
+};
+/**
+ * Number the lines of a hunk. Context lines count on both sides, deletions on
+ * the old side, and additions on the new side; a ``
+ * marker is not a line.
+ * @param hunk - one hunk.
+ * @returns the rows in patch order.
+ */
+export declare function hunkRows(hunk: ForgeDiffHunk): DiffRow[];
+/**
+ * Pair rows for the side-by-side view: each run of deletions sits beside the
+ * run of additions that follows it, row by row, and context rows fill both sides.
+ * @param rows - rows in patch order.
+ * @returns the paired rows.
+ */
+export declare function splitRows(rows: readonly DiffRow[]): SplitRow[];
+/**
+ * Split file text into lines as a patch numbers them; a final line ending ends the last line.
+ * @param text - the file text.
+ * @returns the lines with any carriage returns kept.
+ */
+export declare function textLines(text: string): string[];
+/**
+ * Whether file text is the new side the hunks describe: every context and
+ * added line sits at its number. A file changed after its diff was read fails.
+ * @param lines - the file's lines.
+ * @param hunks - hunks of the file's diff.
+ * @returns whether the lines match.
+ */
+export declare function matchesHunks(lines: readonly string[], hunks: readonly ForgeDiffHunk[]): boolean;
+/**
+ * Lay out one file as runs of rows separated by collapsed unchanged lines.
+ * Unchanged lines before a hunk, between hunks, and after the last hunk
+ * collapse into one gap each; an open gap draws its lines from `lines` once
+ * they are known. The lines after the last hunk are unknown until `lines`
+ * arrives, unless the file is new, deleted, or its last hunk reaches its end.
+ * @param file - one file of a diff.
+ * @param lines - the file's new side, which {@link matchesHunks} accepted, or undefined while it has not been read.
+ * @param open - indexes of the gaps the user expanded.
+ * @returns the segments in file order.
+ */
+export declare function segmentsOf(file: ForgeDiffFile, lines: readonly string[] | undefined, open: ReadonlySet<number>): DiffSegment[];
+/**
+ * Count the rows a file's hunks draw.
+ * @param file - one file of a diff.
+ * @returns the number of context, added, and deleted lines in its hunks.
+ */
+export declare function drawnLines(file: ForgeDiffFile): number;
+//# sourceMappingURL=diff-rows.d.ts.map

package/lib/types/client/file-tree.d.ts

@@ -0,0 +1,33 @@
+import type { ForgeDiffFile } from '../types.ts';
+/** A changed file or a compacted chain of directories containing changed files. */
+export type ChangedFileNode = {
+    readonly kind: 'file';
+    readonly path: string;
+    readonly name: string;
+    readonly file: ForgeDiffFile;
+} | {
+    readonly kind: 'directory';
+    readonly path: string;
+    readonly name: string;
+    readonly children: readonly ChangedFileNode[];
+};
+/**
+ * Build a directory-first tree, compacting directories with a single directory child.
+ * @param files - changed files; Git paths use forward slashes, including on Windows.
+ * @returns the root's children in stable name order.
+ */
+export declare function changedFileTree(files: readonly ForgeDiffFile[]): readonly ChangedFileNode[];
+/**
+ * Read every file in the tree's depth-first display order, independent of navigation folds and filtering.
+ * @param nodes - the complete directory-first tree.
+ * @returns the original file objects in display order.
+ */
+export declare function filesInTreeOrder(nodes: readonly ChangedFileNode[]): readonly ForgeDiffFile[];
+/**
+ * Keep matching files and their ancestors without changing directory identities.
+ * @param nodes - the complete compacted tree.
+ * @param query - case-insensitive text matched against current and previous paths.
+ * @returns matching branches, or the original tree for an empty query.
+ */
+export declare function filterFileTree(nodes: readonly ChangedFileNode[], query: string): readonly ChangedFileNode[];
+//# sourceMappingURL=file-tree.d.ts.map

package/lib/types/client/format.d.ts

@@ -0,0 +1,21 @@
+/** Localized durations and relative times shown on change request cards. */
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { NS } from './locales.ts';
+type Translate = PropsLocale<typeof NS>['t'];
+/**
+ * Format an elapsed time as hours and minutes, minutes and seconds, or seconds.
+ * @param ms - elapsed milliseconds.
+ * @param t - forge panel copy.
+ * @returns the localized duration.
+ */
+export declare function formatDuration(ms: number, t: Translate): string;
+/**
+ * Format how long ago an ISO 8601 time was.
+ * @param iso - the time.
+ * @param now - current epoch milliseconds.
+ * @param t - forge panel copy.
+ * @returns the localized relative time, or undefined when `iso` does not parse.
+ */
+export declare function formatAgo(iso: string, now: number, t: Translate): string | undefined;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/lib/types/client/glyphs.d.ts

@@ -0,0 +1,33 @@
+/** Lifecycle glyphs of change requests and outcome glyphs of their checks. */
+import type { ReactNode } from 'react';
+import type { CheckState } from '@deepseek-ai/dsh-experimental-forge/types';
+import type { ChangeRequestTone } from './status.ts';
+/**
+ * Draw a change request in its lifecycle shape: open, open with a cross for
+ * one that needs its author, draft, merged, closed, or the open shape for an
+ * unknown state.
+ * @param props.tone - lifecycle state that picks the shape and, when tinted, the color.
+ * @param props.tinted - whether the state picks the color; otherwise the glyph uses the current text color.
+ * @param props.size - width and height in pixels, 15 by default.
+ * @param props.label - accessible name; omit it for a decorative glyph.
+ * @returns the SVG glyph.
+ */
+export declare function ChangeRequestGlyph({ tone, tinted, size, label }: {
+    readonly tone: ChangeRequestTone;
+    readonly tinted?: boolean | undefined;
+    readonly size?: number | undefined;
+    readonly label?: string | undefined;
+}): ReactNode;
+/**
+ * Draw the decorative outcome of one check beside its text: a filled circle
+ * for success or failure, a half-filled ring while it runs, and an empty ring
+ * for neutral, skipped, and cancelled checks.
+ * @param props.state - check outcome.
+ * @param props.size - width and height in pixels, 16 by default.
+ * @returns the glyph.
+ */
+export declare function CheckGlyph({ state, size }: {
+    readonly state: CheckState;
+    readonly size?: number | undefined;
+}): ReactNode;
+//# sourceMappingURL=glyphs.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser entry of the forge panel: the sidebar tab, the changes view, the
+ * header button, the worktree option and creation card, and their Remote.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { inject } from './mount.ts';
+export type { ForgePanelKey } from './locales.ts';
+export type { ChangeRequestActions, ChangeRequestCardProps } from './ChangeRequestCard.tsx';
+export type { ChangesParams, ChangesSource, ChangesTarget } from './changes-address.ts';
+export type { ChangesTabInjected, ChangesTabProps } from './ChangesTab.tsx';
+export type { ChangesTabTitleProps } from './ChangesTabTitle.tsx';
+export type { DiffFileAction, DiffFileProps, DiffFileText } from './DiffFile.tsx';
+export type { LocalChangesCardProps } from './LocalChangesCard.tsx';
+export type { ForgeTabInjected, ForgeTabProps } from './ForgeTab.tsx';
+export type { HeaderButtonInjected, HeaderButtonProps } from './HeaderButton.tsx';
+export type { WorktreeProgressInjected, WorktreeProgressProps } from './WorktreeProgress.tsx';
+export type { WorktreeToggleInjected, WorktreeToggleProps } from './WorktreeToggle.tsx';
+export type { ActionNotice, NoticeOptions, PanelSnapshot } from './source.ts';
+/**
+ * Mount the forge panel Remote and its UI.
+ * @param ctx - browser plugin context.
+ * @returns the disposer that withdraws the UI, then the Remote.
+ */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;
+//# sourceMappingURL=index.d.ts.map