paneltir 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -15,6 +15,17 @@ declare const PANELTIR_VERSION: string;
 declare const PANELTIR_FINGERPRINT: string;
 /** How many files that fingerprint covers. */
 declare const PANELTIR_FILE_COUNT: number;
+/**
+ * SHA-256 over `template/` alone — the gate, the seed board and the skill file.
+ *
+ * Separate from the fingerprint above because it answers a different question.
+ * The fingerprint says which build this is; this says whether the files a
+ * project *copied out of* the package are the ones it ships now. Most releases
+ * do not touch `template/`, so those two move at different rates, and a gate
+ * checked against the version number would be reported stale on every release
+ * and believed on none.
+ */
+declare const PANELTIR_TEMPLATE_HASH: string;
 /**
  * Everything needed to report the kit in a panel's own footer or settings
  * sheet, and to check it against the released version without opening
@@ -24,6 +35,8 @@ declare const paneltirBuild: {
     readonly version: string;
     readonly fingerprint: string;
     readonly fileCount: number;
+    /** What `init` stamps, and what a gate is compared against. */
+    readonly templateHash: string;
     /** The tag this build came from, ready to compare or to link. */
     readonly tag: `v${string}`;
     /** Short form, for a footer that has one line to spare. */
@@ -388,7 +401,9 @@ interface GuideTourProps {
      * durable. Leave it out and each reader's browser remembers, which is the
      * right home for a fact about one browser — and the wrong one for a panel
      * with a single owner, who would be told the same tour again on a new
-     * machine.
+     * machine. Passing it does not switch the browser off: a note dismissed
+     * here is written to both, because a caller whose store needs saving would
+     * otherwise lose the dismissal on reload.
      */
     dismissed?: string[];
     /** Told when a note is dismissed. Required for `dismissed` to mean anything. */
@@ -442,7 +457,11 @@ interface NotificationBellProps {
      * make, not the component's, which is why both work.
      */
     seen?: string[];
-    /** Told which ids were just seen. Required for `seen` to mean anything. */
+    /**
+     * Told which ids were just seen. Required for `seen` to mean anything —
+     * though the bell also remembers in localStorage either way, so a caller
+     * that has not saved yet does not show the same notifications again.
+     */
     onSeen?: (ids: string[]) => void;
 }
 declare function NotificationBell({ notifications, labels, seen: given, onSeen }: NotificationBellProps): React.JSX.Element | null;
@@ -517,6 +536,121 @@ interface SetupGuideProps {
 }
 declare function SetupGuide({ requirements, readyMessage, labels }: SetupGuideProps): React.JSX.Element;
 
+/**
+ * The setup, walked one step at a time.
+ *
+ * `SetupGuide` is the list: the right shape for somebody auditing a panel that
+ * already works. This is the other reader — the one who installed it twenty
+ * minutes ago, has four things missing and no idea which to do first. A wall
+ * of four is not four times as useful as one; it is the thing people close.
+ *
+ * Two rules hold it honest. It **checks rather than asks**: every step ends in
+ * a button that re-reads the environment from the server, so the reader is
+ * told whether it worked instead of ticking a box themselves. And it **never
+ * claims what it cannot see**: a panel that could not reach its own endpoint
+ * says the check failed, never that a variable is missing, because telling
+ * somebody to add a token they already added is the worse of the two wrong
+ * answers.
+ *
+ * There is no copy of the values here and nothing is written: the panel cannot
+ * set an environment variable, and a button that appeared to would be the same
+ * fault as one that appeared to install an update.
+ */
+interface SetupWizardLabels {
+    title: string;
+    /** `(index, total)` — "Step 2 of 5". */
+    progress: (index: number, total: number) => string;
+    /** Shown above the one step in hand. */
+    nowDo: string;
+    /** The button that re-reads the environment. */
+    check: string;
+    checking: string;
+    /** Said when a check ran and the step is still not in place. */
+    stillMissing: string;
+    /** Said when the panel could not ask its own server. */
+    cannotTell: string;
+    /** The heading over the finished steps. */
+    doneTitle: string;
+    /** Shown in place of a step when every requirement is in place. */
+    readyTitle: string;
+    readyBody: string;
+    /** The two things to try before trusting the gate, as list items. */
+    verify: string[];
+    /** Closes the wizard. */
+    close: string;
+    /** The escape hatch: heading, explanation, and the prompt to copy. */
+    stuckTitle: string;
+    stuckBody: string;
+    stuckPrompt: string;
+    copy: string;
+    copied: string;
+}
+interface SetupWizardProps {
+    /** In the order they are to be done. The caller owns that order. */
+    requirements: SetupRequirement[];
+    labels: SetupWizardLabels;
+    /** Re-reads the environment. Resolves when the answer has been applied. */
+    onCheck: () => Promise<void> | void;
+    /** Told when the reader closes it. */
+    onClose?: () => void;
+}
+declare function SetupWizard({ requirements, labels, onCheck, onClose }: SetupWizardProps): React.JSX.Element;
+
+/**
+ * Where a reader is in the setup, as one answer instead of a list to read.
+ *
+ * `SetupGuide` draws every requirement at once, which is the right shape for
+ * somebody checking a panel that already works. It is the wrong shape for
+ * somebody who has just installed one: five things at once, four of them
+ * missing, and no order to do them in reads as a wall rather than as a first
+ * step. So the same requirements are walked one at a time, and this is the
+ * function that decides which one.
+ *
+ * The order the caller gives is the order they are done in — a token that
+ * cannot be scoped before the repository is named is a step in the wrong
+ * place, and that is the caller's knowledge, not this function's.
+ */
+interface WizardStep {
+    /** The requirement to show, or null when nothing is left to do. */
+    current: SetupRequirement | null;
+    /** 1-based, for "step 2 of 5". Zero when there is nothing left. */
+    index: number;
+    /** How many steps this setup has in total. */
+    total: number;
+    /** Every requirement that is in place, in the caller's order. */
+    done: SetupRequirement[];
+    /** True when every requirement is `ok`. */
+    ready: boolean;
+    /**
+     * True when the panel could not ask the server, so nothing is claimed.
+     *
+     * This is not "not ready": a panel that cannot reach its own endpoint knows
+     * nothing about the environment, and telling somebody to add a token they
+     * already added is worse than saying the check itself failed.
+     */
+    unknown: boolean;
+}
+declare function wizardStep(requirements: SetupRequirement[]): WizardStep;
+/**
+ * Whether this panel has never been worked, which is what "first install"
+ * means here.
+ *
+ * `paneltir init` writes a board with the columns already there and nothing
+ * on them, so a board carrying no cards and no runs is one nobody has used
+ * yet. That is a better signal than a version on disk: a project can install
+ * the package, never open the panel, and update three times before anyone
+ * sees it — and it is still that reader's first run.
+ *
+ * A panel that has been worked and then loses a variable is deliberately not
+ * this. It needs the same instructions and gets them from the same wizard,
+ * but it is told rather than taken over: somebody mid-sentence on a board
+ * they know does not want a walkthrough opening on top of it.
+ */
+declare function isFirstRun(board: {
+    cards?: unknown[];
+    runs?: unknown[];
+}): boolean;
+
 type Handler = (payload: Record<string, string>, event: MouseEvent) => void;
 /**
  * A single click listener on document that dispatches by data-* attributes,
@@ -1035,6 +1169,27 @@ interface PanelTheme {
 type PanelThemes = Record<string, PanelTheme>;
 /** Every preset the kit ships, as a panel would offer them. */
 declare const PRESET_PANEL_THEMES: PanelThemes;
+/**
+ * The identities a panel actually offers, given what its caller asked for.
+ *
+ * `themes` is the exact set: these and nothing else. `extraThemes` adds to the
+ * presets, which is what a project installing the panel nearly always means —
+ * it has one identity of its own and no reason to lose the four the kit ships.
+ *
+ * The distinction exists because the absence of it cost two real installs. A
+ * default parameter is replaced, not merged, so a project passing its own
+ * theme as `themes` silently deleted every preset and its settings sheet
+ * offered exactly one row. `INSTALL.md` led there — it said to derive the
+ * project's palette and then listed `themes` as the prop for identities — so
+ * the reader followed the instructions and the API was the thing that was
+ * wrong.
+ *
+ * Extras come first, because `defaultTheme` falls back to the first key: a
+ * panel should open in the project's own identity, not in a preset that
+ * happens to sort ahead of it. A key that collides with a preset belongs to
+ * the caller — they named it, so they meant it.
+ */
+declare function offeredThemes(themes?: PanelThemes, extraThemes?: PanelThemes): PanelThemes;
 
 /**
  * What the panel shows for the dfklabs catalogue, and the three ways to
@@ -1136,6 +1291,12 @@ interface UiStrings {
     updateAsOrder: string;
     updateAsOrderHow: string;
     notifUpdate: string;
+    releaseTitle: (version: string) => string;
+    releaseDate: (date: string) => string;
+    releaseShape: Record<'breaking' | 'feature' | 'fix' | 'chore', string>;
+    releaseKind: Record<'breaking' | 'feature' | 'fix' | 'chore', string>;
+    releaseClose: string;
+    releaseNone: string;
     updateCardTitle: (version: string) => string;
     updateCardBody: (version: string) => string;
     cardDetail: string;
@@ -1213,11 +1374,33 @@ interface UiStrings {
     needTokenEnables: string;
     needRepo: string;
     needRepoEnables: string;
+    needGate: string;
+    needGateEnables: string;
+    fixGate: string;
     fixTokenCreate: string;
     fixTokenScope: string;
     fixTokenPaste: string;
     fixTokenRedeploy: string;
     fixRepo: string;
+    wizardTitle: string;
+    wizardProgress: (index: number, total: number) => string;
+    wizardNowDo: string;
+    wizardCheck: string;
+    wizardChecking: string;
+    wizardStillMissing: string;
+    wizardCannotTell: string;
+    wizardDoneTitle: string;
+    wizardReadyTitle: string;
+    wizardReadyBody: string;
+    wizardVerify: string[];
+    wizardClose: string;
+    wizardStuckTitle: string;
+    wizardStuckBody: string;
+    wizardStuckPrompt: string;
+    wizardCopy: string;
+    wizardCopied: string;
+    wizardOpen: string;
+    wizardBanner: string;
     demoTourWelcomeTitle: string;
     demoTourWelcomeBody: string;
     demoTourBoardTitle: string;
@@ -1292,6 +1475,10 @@ interface UiStrings {
     suggestionStatuses: Record<'new' | 'doing' | 'done' | 'dismissed', string>;
     analysisSections: Record<AnalysisSection, string>;
     analysisSectionHints: Record<AnalysisSection, string>;
+    analysisRedo: string;
+    analysisRedoAsked: string;
+    analysisRedoTitle: Record<AnalysisSection, string>;
+    analysisRedoBody: Record<AnalysisSection, string>;
     analysisAnswered: (answered: number, total: number) => string;
     analysisAllDecided: string;
     choicesTitle: string;
@@ -1400,13 +1587,41 @@ interface Capability {
 }
 declare const CAPABILITIES: Capability[];
 
+type ThemeChoice = string;
 interface PanelAppProps {
     state: PanelState;
     /**
-     * The identities the settings sheet offers. Defaults to the kit's presets,
-     * so a panel has something to switch between on its first session.
+     * The exact identities the settings sheet offers: these and nothing else.
+     *
+     * Almost nobody wants this. A project with one identity of its own wants
+     * `extraThemes`, which adds to the presets instead of replacing them — this
+     * prop silently deleted all four for two real installs, whose settings sheet
+     * then offered a single row.
      */
     themes?: PanelThemes;
+    /**
+     * Identities of the caller's own, offered *alongside* the kit's presets.
+     *
+     * This is what a project installing the panel means. They come first, so the
+     * panel opens in the project's identity rather than in a preset; a key that
+     * collides with a preset replaces it, because the caller named it.
+     */
+    extraThemes?: PanelThemes;
+    /**
+     * `.paneltir/gate.json` from this project, if the caller imports it.
+     *
+     * The gate is copied once and then belongs to the project, which means it is
+     * the one part of this package that can never be told it is old — and that
+     * has cost two releases already. Handing the stamp in lets the panel say so,
+     * with no filesystem and no network, because both halves of the comparison
+     * are already data: the stamp from the project and `templateHash` from the
+     * installed package.
+     *
+     * Omitted, the panel says nothing about the gate rather than guessing. This
+     * is a prop and not a fetch for the reason the Tools screen is a prop in the
+     * demo: the kit does not decide what a caller's server can be asked.
+     */
+    gate?: unknown;
     /** Which one to draw before the board has said. Defaults to the first. */
     defaultTheme?: string;
     /**
@@ -1417,8 +1632,16 @@ interface PanelAppProps {
      * business drawing anybody's mark, including its own.
      */
     brand?: React.ReactNode;
-    /** Rendered inside the theme provider, behind everything: a caller's screen effects. */
-    decoration?: React.ReactNode;
+    /**
+     * Rendered inside the theme provider, behind everything: a caller's screen
+     * effects.
+     *
+     * It may be a function of the theme in force, because a decoration usually
+     * belongs to one theme rather than to the panel. This project's scanlines
+     * are Night City's and were drawn over every other theme until this existed
+     * — a palette swapped underneath an effect that did not move with it.
+     */
+    decoration?: React.ReactNode | ((theme: ThemeChoice) => React.ReactNode);
     /** Put on the theme root, so a caller's stylesheet has something to hang on. */
     className?: string;
     /** Rendered under the panel. A caller's footer, or nothing. */
@@ -1465,7 +1688,94 @@ interface PanelAppProps {
         fileCount: number;
     };
 }
-declare function PanelApp({ state: initialState, themes, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, checkForUpdates, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
+declare function PanelApp({ state: initialState, themes: exactThemes, extraThemes, gate, defaultTheme, brand, decoration, className, footer, links, capabilities, extras, showLanguage, showHistory, checkForUpdates, saveEndpoint, marketplaceEndpoint, marketplaceReport, fingerprint, }: PanelAppProps): React.JSX.Element;
+
+/**
+ * Whether the gate a project is running is the gate this version ships.
+ *
+ * `template/` is the one thing here that leaves as *files a project keeps*.
+ * The components arrive in `node_modules` and are replaced on every update;
+ * the gate is copied once by `init` and is then that project's own — which is
+ * the point, since it holds their password rule and points at their
+ * repository, and a front door that moves when a library updates is not a
+ * front door.
+ *
+ * The cost of that is a copy that can never be told it is old. It has already
+ * been paid twice. The `HTTP 500` fix landed in `template/api/panel-state.ts`,
+ * so every project installed before it still has a save that cannot work, and
+ * nothing anywhere says so; `.claude/skills/panel/SKILL.md` is copied the same
+ * way, so a rule learned upstream never reaches the Claude that reads it.
+ * Upstream the copy is held honest by `test:auth` and `test:board`. Downstream
+ * there was nothing at all.
+ *
+ * So `init` records what it copied and what it copied it from, and this says
+ * what that record means. Two rules shape it:
+ *
+ * - **It compares hashes, not version numbers.** Most releases do not touch
+ *   `template/`, so "you are on 0.6.0 and 0.9.0 exists" would cry wolf for
+ *   every release and be ignored by the one that mattered. `templateHash`
+ *   ships inside `fingerprint.json`, so the comparison is exact.
+ * - **It needs no filesystem and no network**, because the panel runs in a
+ *   browser and has neither. Everything it judges is data the caller already
+ *   holds: the stamp from the project, the hash from the installed package.
+ *
+ * It reports and never repairs. Replacing somebody's gate is `init --force`,
+ * typed by a person who has read what changed.
+ */
+/**
+ * What `init` wrote, and what it wrote it from.
+ *
+ * Lives at `.paneltir/gate.json` in the project. It is not a lockfile and
+ * nothing resolves against it — it exists so a later session can tell "you
+ * edited this" from "we changed this underneath you", which is the distinction
+ * a bare diff cannot make.
+ */
+interface GateStamp {
+    /** The kit version that copied these files. */
+    version: string;
+    /** `templateHash` from that version's `fingerprint.json`. */
+    templateHash: string;
+    /** When, so a reader can date it against their own git history. */
+    copiedAt: string;
+    /**
+     * SHA-256 of each file as written, keyed by its path in the project.
+     *
+     * This is what separates a file the project edited from one the template
+     * moved under. Absent for a file `init` left alone: we did not write it, so
+     * we cannot claim to know where it came from.
+     */
+    files: Record<string, string>;
+}
+type GateVerdict = 
+/** The gate is the one this version ships. */
+'current'
+/** `template/` has changed since this gate was copied. */
+ | 'behind'
+/**
+ * No stamp. Every project installed before stamping existed is here, and it
+ * is not a fault — it is the absence of an answer, which is why it is not
+ * called one. `paneltir doctor` can still compare the files themselves.
+ */
+ | 'unstamped';
+interface GateReading {
+    verdict: GateVerdict;
+    /** The version that copied the gate, when a stamp says so. */
+    copiedFrom?: string;
+    /** The version running now. */
+    installed: string;
+}
+/**
+ * Reads a stamp against the installed package.
+ *
+ * Deliberately total: a malformed or absent stamp answers `unstamped` rather
+ * than throwing. This is called while a panel is drawing, and a panel that
+ * fails to open because it could not classify its own gate would be a worse
+ * outcome than the drift it was looking for.
+ */
+declare function gateStatus(stamp: unknown, installed: {
+    version: string;
+    templateHash?: string;
+}): GateReading;
 
 /**
  * Applies a board move to the flat card list.
@@ -1490,8 +1800,16 @@ interface AnalysisViewProps {
     onDecide: (section: AnalysisSection, choiceId: string, optionId: string | null) => void;
     /** Opening the card a fact is about, so a number is never a dead end. */
     onOpenCard?: (id: string) => void;
+    /**
+     * Asks for this screen's analysis to be worked again.
+     *
+     * The panel cannot run Claude, so it writes a card and says so. A button
+     * that appeared to fetch a report and did not would be the exact fault the
+     * derived theme's refresh already avoids. Omit it and no button is drawn.
+     */
+    onRequestReport?: (section: AnalysisSection) => void;
 }
-declare function AnalysisView({ analysis, cards, columns, today, lang, ui, onChooseStrategy, onSuggestionStatus, onDecide, onOpenCard, }: AnalysisViewProps): React.JSX.Element;
+declare function AnalysisView({ analysis, cards, columns, today, lang, ui, onChooseStrategy, onSuggestionStatus, onDecide, onOpenCard, onRequestReport, }: AnalysisViewProps): React.JSX.Element;
 
 interface MarketplaceViewProps {
     /** Null while the catalogue is still being asked for. */
@@ -1517,4 +1835,4 @@ interface CardSheetProps {
 }
 declare function CardSheet({ card, state, lang, ui, onChange, onDelete, onClose }: CardSheetProps): React.JSX.Element | null;
 
-export { ANALYSIS_SECTIONS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, type Severity, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, emptyCard, explainBoard, isCard, ledgerForm, midnightTheme, moveCardInColumns, newId, oldMoneyTheme, panelForm, paneltirBuild, paperForm, readBoard, readStoredLang, repositorySnippet, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, writeText };
+export { ANALYSIS_SECTIONS, AlertBanner, type AlertBannerProps, type Analysis, type AnalysisSection, AnalysisView, BOARD_VERSION, Board, type BoardCardData, type BoardCheck, type BoardColumnData, type BoardFacts, type BoardMoveResult, type BoardProblem, type BoardProps, type BoardTag, CAPABILITIES, type Capability, Card$1 as Card, type CardProps, CardSheet, type Check, type Choice, type ChoiceOption, type ColumnDef, type Competitor, type Constraint, CopyBlock, type CopyBlockLabels, type CopyBlockProps, type Counts, DashboardHeader, type DashboardHeaderProps, type DashboardThemeForm, DashboardThemeProvider, type DashboardThemeTokens, DetailSection, type DetailSectionProps, DetailSheet, type DetailSheetProps, FilterChip, type FilterChipProps, FilterChipRow, type GateReading, type GateStamp, type GateVerdict, type Goal, GuideNote, type GuideNoteProps, GuideTour, type GuideTourProps, type HealthFact, HealthPill, type HealthPillProps, HealthPillRow, type HealthStatus, INTENTS, INTENT_COPY, type ImportedTheme, type InstallState, type Intent, type IntentCopy, LANGS, LANG_LABELS, LEVELS, type Lang, type Level, MARKETPLACE_NAME, MARKETPLACE_URL, type Market, type MarketplaceReport, type MarketplaceTool, MarketplaceView, type Metric, type Note, NotificationBell, type NotificationBellProps, type NotificationLabels, type NotificationTone, OWNERS, type Owner, PANELTIR_FILE_COUNT, PANELTIR_FINGERPRINT, PANELTIR_TEMPLATE_HASH, PANELTIR_VERSION, PRESET_PANEL_THEMES, PanelApp, type PanelAppProps, type Card as PanelCard, type PanelNotification, type PanelState, type PanelTheme, type PanelThemes, type Preferences, type Reading, type Run, SetupGuide, type SetupGuideProps, type SetupRequirement, type SetupStatus, SetupWizard, type SetupWizardLabels, type SetupWizardProps, type Severity, StatTile, StatTileGrid, type StatTileProps, type Strategy, type Suggestion, type SuggestionStatus, THEME_FORMS, THEME_PRESETS, type Text, type ThemeFormName, type ThemePresetName, type Trend, UI, type UiStrings, type Weight, type WizardStep, applyMove, boardFacts, checkProgress, claimedWithoutStarting, claudeTheme, commandSnippet, countCards, cyberpunkTheme, decided, emptyCard, explainBoard, gateStatus, isCard, isFirstRun, ledgerForm, midnightTheme, moveCardInColumns, newId, offeredThemes, oldMoneyTheme, panelForm, paneltirBuild, paperForm, readBoard, readStoredLang, repositorySnippet, resetGuide, sparkPoints, stampForColumn, storeLang, text, today, trendOf, undecided, untranslated, useDashboardForm, useDashboardTheme, useDelegatedClick, useGuideNote, useMediaQuery, validateBoard, wizardStep, writeText };