@ham2k/extension-sdk 0.5.4 → 0.5.6

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-// @ham2k/extension-sdk 0.5.4
+// @ham2k/extension-sdk 0.5.6
 /** Experimental v1 scene contract. All coordinates are in the scene's viewBox. */
 export interface SvgScene {
 	version: 1;
@@ -102,7 +102,7 @@ export interface SvgSceneControl {
 	hover?: boolean;
 	/** Accessible descriptions indexed by (value - min) / step. */
 	valueLabels?: string[];
-	/** Knobs use relative horizontal/upward dragging. Default: step per scene unit. */
+	/** Knobs use relative horizontal/upward dragging. Value per scene unit; default 1. */
 	sensitivity?: number;
 }
 export interface PanelSceneEvent {
@@ -236,6 +236,7 @@ export interface HookContext {
 export interface HistoryForCallOptions {
 	refType?: string | string[];
 	refPrefix?: string | string[];
+	refsSegmentAware?: boolean;
 	operation?: string | string[];
 	excludeOperation?: string | string[];
 	fromDate?: string;
@@ -392,6 +393,7 @@ export interface RefGeojson {
 export interface LoggingControlDescriptor {
 	key: string;
 	label: string;
+	shortLabel?: string;
 	icon?: string;
 	color?: string;
 	order?: number;
@@ -631,12 +633,14 @@ export interface ScoreQsosRequest {
 	segments?: OperationSegmentPayload[];
 	ref?: Record<string, JSONValue>;
 	resumeFrom?: JSONValue;
+	resumeDay?: number;
 }
 export interface ScoreQsosResult {
 	qsoScores: Record<string, QsoScoreVerdict>;
 	daySections: DayScoreSummary[];
 	operationSummary: Record<string, ScoreTally>;
 	scoresheet?: JSONValue;
+	scoresheetDay?: number;
 }
 export interface ScoreQsoRequest {
 	operation: Record<string, JSONValue>;
@@ -645,6 +649,8 @@ export interface ScoreQsoRequest {
 	ref?: Record<string, JSONValue>;
 	segments?: OperationSegmentPayload[];
 	resumeFrom?: JSONValue;
+	resumeDay?: number;
+	qsos?: Record<string, JSONValue>[];
 }
 export interface QsoScoreNotices {
 	notices: string[];
@@ -660,6 +666,8 @@ export interface ScoreCandidatesRequest {
 	ref?: Record<string, JSONValue>;
 	segments?: OperationSegmentPayload[];
 	resumeFrom?: JSONValue;
+	resumeDay?: number;
+	qsos?: Record<string, JSONValue>[];
 }
 export type ScoreCandidatesResult = Record<string, QsoScoreNotices>;
 export interface ScoringHook {
@@ -707,6 +715,10 @@ export interface CommandAction {
 		wpm: number;
 	};
 	showKeyer?: Record<string, never>;
+	setEnterSends?: {
+		on?: boolean;
+		running?: boolean;
+	};
 	updateQso?: Record<string, JSONValue>;
 	addQso?: Record<string, JSONValue>;
 	sendSpots?: {

package/dist/scoring.js

@@ -1,7 +1,10 @@
 const DAY_IN_MILLIS = 1e3 * 60 * 60 * 24;
-function copyCheckpoint(sheet) {
+function copySheet(sheet) {
   return JSON.parse(JSON.stringify(sheet));
 }
+function openCheckpoint(resumeFrom, resumeDay) {
+  return { sheet: copySheet(resumeFrom), day: typeof resumeDay === "number" ? resumeDay : void 0 };
+}
 function dayOf(qso) {
   const millis = Number(qso.startAtMillis ?? 0);
   return millis - millis % DAY_IN_MILLIS;
@@ -27,9 +30,9 @@ function contestScorer(scorer, options = {}) {
     const refs = operation.refs ?? [];
     return refs.find((r) => typeof r?.type === "string" && scopedRefTypes.includes(r.type));
   }
-  function fold(scoresheet, qsos, args, ctx, onQso, onDayEnd, segments) {
+  function fold(scoresheet, qsos, args, ctx, onQso, onDayEnd, segments, startDay) {
     let sheet = scoresheet;
-    let currentDay;
+    let currentDay = startDay;
     let dayCount = 0;
     const timeline = segments && segments.length > 1 ? segments : void 0;
     let segmentIndex = 0;
@@ -60,11 +63,14 @@ function contestScorer(scorer, options = {}) {
       onQso?.(typeof qso.uuid === "string" ? qso.uuid : void 0, result.score);
     }
     if (currentDay !== void 0) onDayEnd?.(currentDay, dayCount, sheet);
-    return sheet;
+    return { sheet, day: currentDay };
   }
   async function liveScoresheet(args, ctx, excludeUuid) {
     if (args.resumeFrom !== void 0) {
-      return copyCheckpoint(args.resumeFrom);
+      const { sheet, day } = openCheckpoint(args.resumeFrom, args.resumeDay);
+      const tail = chronological(args.qsos ?? []).filter((q) => !excludeUuid || q.uuid !== excludeUuid);
+      if (tail.length === 0) return { sheet, day };
+      return fold(sheet, tail, args, ctx, void 0, void 0, args.segments, day);
     }
     const uuid = typeof args.operation.uuid === "string" ? args.operation.uuid : void 0;
     const log = uuid ? await ctx.getQsos?.(uuid) ?? [] : [];
@@ -85,10 +91,11 @@ function contestScorer(scorer, options = {}) {
     scope,
     async scoreQsos(args, ctx) {
       const qsos = chronological(args.qsos);
-      const start = args.resumeFrom !== void 0 ? copyCheckpoint(args.resumeFrom) : scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx);
+      const resumed = args.resumeFrom !== void 0 ? openCheckpoint(args.resumeFrom, args.resumeDay) : void 0;
+      const start = resumed?.sheet ?? scorer.startScoresheet({ operation: args.operation, ref: args.ref }, ctx);
       const qsoScores = {};
       const daySections = [];
-      const end = fold(
+      const { sheet: end, day: endDay } = fold(
         start,
         qsos,
         args,
@@ -103,7 +110,8 @@ function contestScorer(scorer, options = {}) {
             scores: scorer.summarizeScore({ scoresheet: sheet, operation: args.operation, ref: args.ref, scope: "day" }, ctx)
           });
         },
-        args.segments
+        args.segments,
+        resumed?.day
       );
       return {
         qsoScores,
@@ -112,14 +120,15 @@ function contestScorer(scorer, options = {}) {
           { scoresheet: end, operation: args.operation, ref: args.ref, scope: "operation" },
           ctx
         ),
-        scoresheet: end
+        scoresheet: end,
+        ...endDay !== void 0 && { scoresheetDay: endDay }
       };
     },
     /// Live path: score the candidate against the log so far and report only
     /// its notices/alerts. Nothing is recorded — the resulting scoresheet is
     /// discarded, which is exactly why one `scoreQso` can serve both paths.
     async scoreQso(args, ctx) {
-      const sheet = await liveScoresheet(args, ctx, args.excludeUuid);
+      const { sheet } = await liveScoresheet(args, ctx, args.excludeUuid);
       const { score } = scorer.scoreQso(
         { scoresheet: sheet, qso: candidateAsOfNow(args.qso), operation: args.operation, ref: args.ref, isNewDay: false },
         ctx
@@ -138,12 +147,12 @@ function contestScorer(scorer, options = {}) {
     /// contract that makes the batch fold linear. Without it the first
     /// candidate's call would count as worked for every candidate after it.
     async scoreCandidates(args, ctx) {
-      const base = await liveScoresheet(args, ctx);
+      const { sheet: base } = await liveScoresheet(args, ctx);
       const result = {};
       for (const candidate of args.candidates) {
         const { score } = scorer.scoreQso(
           {
-            scoresheet: copyCheckpoint(base),
+            scoresheet: copySheet(base),
             qso: candidateAsOfNow(candidate.qso),
             operation: args.operation,
             ref: args.ref,

package/docs/hooks.md

@@ -64,10 +64,14 @@ hook method receives `(args, ctx)` where `ctx: HookContext` is:
   `options` (`HistoryForCallOptions` in `types.ts`) narrow the history
   before it is ordered and limited, so `{ refType: 'cwt' }` finds last
   month's CWT exchange behind a week of POTA contacts. The filters are
-  `refType` (a ref in the QSO's own `refs`), `refPrefix` (a ref whose `ref`
-  starts with it, ignoring ASCII case; with `refType`, the same ref must pass
-  both, so `{ refType: 'potaActivation', refPrefix: 'FR-' }` finds French
-  parks), `operation`/`excludeOperation`,
+  `refType` (a ref in the QSO's own `refs` or its operation's, since an
+  activation's ref lives on the operation), `refPrefix` (such a ref whose
+  `ref` starts with it, ignoring ASCII case; with `refType`, the same ref
+  must pass both, so `{ refType: 'potaActivation', refPrefix: 'FR-' }` finds
+  every contact made activating a French park; an operation's refs are its
+  base ones unless `refsSegmentAware: true`, which reads them as they stood
+  at each contact, so a rove's second park or a contest that ended at a
+  break is seen), `operation`/`excludeOperation`,
   `band`/`excludeBand`, `mode`/`excludeMode` (`SSB` also matches its
   sidebands, and `CW`/`PHONE`/`DATA` match their whole family), whole UTC
   days through `fromDate`/`toDate` or `fromDateMillis`/`toDateMillis`, and
@@ -495,8 +499,11 @@ interface ActivityHook {
   suggest?(args: SuggestArgs, ctx): Promise<ActivitySuggestion[]>
   processQsoBeforeSave?(args: { qso, operation }, ctx): Promise<Patch | null>
 }
-// LoggingControlDescriptor: {key, label, icon?, color?, order?, optionType?,
-//   allowsMultiple?, editable?, input}
+// LoggingControlDescriptor: {key, label, shortLabel?, icon?, color?, order?,
+//   optionType?, allowsMultiple?, editable?, input}
+// `shortLabel` is the same name in fewer characters, for a field the logging
+// row has squeezed below its label's width. The core measures and picks; the
+// extension only says what the short form is.
 // SuggestArgs: {operation, location?: {lat, lon}, callsign?, searchTerm?, scoped?}
 // ActivitySuggestion: Ref & {distance?, relevance?, allowsMultiple?}
 
@@ -847,7 +854,7 @@ interface CommandHook {
 // CommandInterpretation: {expectsParams?, mixedCase?, error?, describe?, confirm?, commands?: CommandAction[]}
 // CommandCatalogEntry: {command, describe, params?, category?, needsOperation?, expectsParams?, suggest?}
 // CommandAction (closed set): {setVfo?, setPower?, updateQso?, addQso?,
-//   setKeyerSpeed?, showKeyer?, sendSpots?, syncAll?, updateSettings?, updateSetting?, openSettings?,
+//   setKeyerSpeed?, showKeyer?, setEnterSends?, sendSpots?, syncAll?, updateSettings?, updateSetting?, openSettings?,
 //   updateOperation?, markSegment?, setCallField?, reloadDataFiles?, devNotice?, devStatus?,
 //   devProgress?, devHammer?, devSplash?, devOnboard?, devTester?, devPopup?,
 //   devTimeTravel?, toggleExperiment?}
@@ -1164,14 +1171,16 @@ interface ScoringHook {
   scoreQso?(args: ScoreQsoRequest, ctx): Promise<QsoScoreNotices>
   scoreCandidates?(args: ScoreCandidatesRequest, ctx): Promise<ScoreCandidatesResult>
 }
-// ScoreQsosRequest: {operation, qsos, ref?, resumeFrom?}
+// ScoreQsosRequest: {operation, qsos, ref?, segments?, resumeFrom?, resumeDay?}
 // ScoreQsosResult:  {
 //   qsoScores: Record<uuid, QsoScoreVerdict>,   // one per QSO claimed; see above
 //   daySections: {day, count, scores: Record<tallyKey, ScoreTally>}[],
 //   operationSummary: Record<tallyKey, ScoreTally>,
 //   scoresheet,                                  // checkpoint to resume from
+//   scoresheetDay?,                              // the day it ends on, handed back as resumeDay
 // }
-// ScoreCandidatesRequest: {operation, candidates: {key, qso}[], ref?, segments?, resumeFrom?}
+// ScoreQsoRequest:        {operation, qso, excludeUuid?, ref?, segments?, resumeFrom?, resumeDay?, qsos?}
+// ScoreCandidatesRequest: {operation, candidates: {key, qso}[], ref?, segments?, resumeFrom?, resumeDay?, qsos?}
 // ScoreCandidatesResult:  Record<candidateKey, QsoScoreNotices>
 ```
 
@@ -1183,7 +1192,15 @@ both live paths for free.
 A candidate that carries no `startAtMillis` (the draft's time is still
 automatic) reaches the scorer stamped with the current time on both live
 paths, so a day-bucketed rule judges it as of now rather than at the epoch; a
-candidate that states a time keeps it.
+candidate that states a time keeps it. On both live paths a `resumeFrom`
+checkpoint, with the `qsos` logged since it, stands in for the whole-log read:
+the harness copies the checkpoint, replays that tail onto it (continuing the
+day `resumeDay` names, so no scorer's per-day tally restarts mid-day) and
+scores the candidate against the result. The host sends a checkpoint only when
+it can prove the log is what the checkpoint folded plus appended contacts
+(`scoreQso`), or when the log has not moved since the checkpoint was written
+(`scoreCandidates`, which sends no tail yet); otherwise the harness reads the
+log through `ctx.getQsos` and folds it cold.
 `scoreCandidates` answers the same question for many at once, which is what the
 Spots Panel asks to mark the spots already worked: the log is folded once per
 scorer and every candidate scored against a COPY of the result, so no candidate
@@ -1284,13 +1301,14 @@ numeric value patches; local-only controls and animation frames make no bridge
 calls. Controls with `continuous: true` send `change` events during dragging and a
 final `commit` on release; pending movements are coalesced to the newest value.
 Numeric text supports `scale`, `truncate`, `modulo`, and `minIntegerDigits`
-for local numeric formatting. KI2D’s Radio Panel uses these for its Modern
+for local numeric formatting; bindings accept `scale`, `truncate` and `modulo`
+too, applied to the value before the ramp. KI2D’s Radio Panel uses these for its Modern
 frequency groups; its settings offer Modern/LCD styles and radio selection. Local sliders may use `hover` and `discrete` hourly buckets. Text `samples`
 may hold numbers or preformatted strings; control `valueLabels` supplies accessible
 value descriptions. Transform/opacity bindings may also supply numeric `samples`,
 equally spaced over their `input` range, instead of the `output` ramp. The host
 interpolates and clamps these locally; chart markers and callouts can follow
-individual readings without bridge calls. See [the prototype contract and migration plan](https://github.com/ham2k/halo/blob/main/docs/design/svg-scenes.md)
+individual readings without bridge calls. See [the design notes and open milestones](https://github.com/ham2k/halo/blob/main/docs/design/svg-scenes.md)
 and the `k2hrc-svg-scenes` sample. This API is experimental.
 
 Scene-capable hosts also supply `args.environment` on **render and event** calls:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ham2k/extension-sdk",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Write extensions for the Ham2K Logger: typed hook contracts and the host API",
   "keywords": [
     "ham2k",