linked-rolls 0.70.0 → 0.72.0

package/lib/ops/beliefs.js

@@ -10,22 +10,44 @@ const onBeliefAt = (path, op) => onAssumptionAt(path, assumption => {
     if (belief)
         op(belief);
 });
-/** Annotates the assumption at the path with a belief held true, for reasons to be added. */
+/**
+ * Annotates the assumption at the path with a belief held true, for reasons to be added.
+ * @category Operations
+ */
 export const createBelief = (path) => onAssumptionAt(path, assumption => {
     assumption['@annotation'] = {
         id: v4(),
         belief: { type: 'belief', id: v4(), certainty: 'true', reasons: [] }
     };
 });
+/**
+ * Takes the belief off the assumption at the path, which leaves the
+ * statement stated plainly.
+ * @category Operations
+ */
 export const clearBelief = (path) => onAssumptionAt(path, assumption => {
     delete assumption['@annotation'];
 });
+/**
+ * Sets the certainty the belief on the assumption at the path is held
+ * with.
+ * @category Operations
+ */
 export const setCertainty = (path, certainty) => onBeliefAt(path, belief => {
     belief.certainty = certainty;
 });
+/**
+ * Adds a reason to the belief on the assumption at the path.
+ * @category Operations
+ */
 export const addReason = (path, reason) => onBeliefAt(path, belief => {
     belief.reasons.push(reason);
 });
+/**
+ * Takes the reason at the index off the belief on the assumption at the
+ * path.
+ * @category Operations
+ */
 export const removeReason = (path, index) => onBeliefAt(path, belief => {
     belief.reasons.splice(index, 1);
 });

package/lib/ops/collation.d.ts

@@ -26,12 +26,14 @@ import { EditionOp } from "./draft.js";
  * A version is based on itself or on one of its own descendants in no
  * statement, since the stemma would loop; asked for that, nothing
  * changes.
+ * @category Operations
  */
 export declare const connectVersions: (childId: string, parentId: string, tolerance?: ObjectAssumption<CollationTolerance>) => EditionOp;
 /**
  * Folds the version's own symbols into those it inherits and collates
  * with: the carriers pass over, and the insertions go. Collates at the
  * tolerance of the derivation, where the caller names none.
+ * @category Operations
  */
 export declare const collateSymbols: (versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
 /**
@@ -57,5 +59,6 @@ export declare const collateSymbols: (versionId: string, symbolIds: readonly str
  * and are passed over, so a reading somebody has separated by hand
  * keeps its identifier and the edit that speaks for it. Named symbols
  * narrow the act to those; naming none separates the whole reading.
+ * @category Operations
  */
 export declare const separateReadings: (versionId: string, copies: ReadonlySet<string>, symbolIds?: readonly string[]) => EditionOp;

package/lib/ops/collation.js

@@ -60,6 +60,7 @@ const byExchange = (edits) => new Map(edits.map(edit => [exchangeKey((edit.inser
  * A version is based on itself or on one of its own descendants in no
  * statement, since the stemma would loop; asked for that, nothing
  * changes.
+ * @category Operations
  */
 export const connectVersions = (childId, parentId, tolerance = defaultCollationTolerance) => reading(edition => {
     if (childId === parentId || derivesFrom(edition.versions, parentId, childId))
@@ -132,6 +133,7 @@ export const connectVersions = (childId, parentId, tolerance = defaultCollationT
  * Folds the version's own symbols into those it inherits and collates
  * with: the carriers pass over, and the insertions go. Collates at the
  * tolerance of the derivation, where the caller names none.
+ * @category Operations
  */
 export const collateSymbols = (versionId, symbolIds, tolerance) => reading(edition => {
     const version = versionIn(edition, versionId);
@@ -201,6 +203,7 @@ const sharedWith = (edition, symbol, copies) => {
  * and are passed over, so a reading somebody has separated by hand
  * keeps its identifier and the edit that speaks for it. Named symbols
  * narrow the act to those; naming none separates the whole reading.
+ * @category Operations
  */
 export const separateReadings = (versionId, copies, symbolIds) => reading(edition => {
     const version = versionIn(edition, versionId);

package/lib/ops/commands.d.ts

@@ -1,8 +1,23 @@
 import { PlacementRelation } from "../model/Symbol.js";
 import { EditionOp } from "./draft.js";
-/** States how the follower is placed relative to the reference, in place of any earlier statement. */
+/**
+ * States how the follower is placed relative to the reference, in place of any earlier statement.
+ * @category Operations
+ */
 export declare const placeCommand: (followerId: string, referenceId: string, relation: PlacementRelation) => EditionOp;
+/**
+ * Withdraws the statement placing the command relative to another,
+ * whichever relation it states.
+ * @category Operations
+ */
 export declare const unplaceCommand: (followerId: string) => EditionOp;
-/** The pair is stated on `statingId` only, as the format asks. */
+/**
+ * The pair is stated on `statingId` only, as the format asks.
+ * @category Operations
+ */
 export declare const pairCommands: (statingId: string, partnerId: string) => EditionOp;
+/**
+ * Withdraws the pairing the command states.
+ * @category Operations
+ */
 export declare const unpairCommand: (statingId: string) => EditionOp;

package/lib/ops/commands.js

@@ -14,16 +14,31 @@ const onCommand = (id, op) => reading(edition => draft => {
         op(symbol);
 });
 const clearPlacement = (command) => placementRelations.forEach(relation => { delete command[relation]; });
-/** States how the follower is placed relative to the reference, in place of any earlier statement. */
+/**
+ * States how the follower is placed relative to the reference, in place of any earlier statement.
+ * @category Operations
+ */
 export const placeCommand = (followerId, referenceId, relation) => onCommand(followerId, command => {
     clearPlacement(command);
     command[relation] = assignReference(referenceId);
 });
+/**
+ * Withdraws the statement placing the command relative to another,
+ * whichever relation it states.
+ * @category Operations
+ */
 export const unplaceCommand = (followerId) => onCommand(followerId, clearPlacement);
-/** The pair is stated on `statingId` only, as the format asks. */
+/**
+ * The pair is stated on `statingId` only, as the format asks.
+ * @category Operations
+ */
 export const pairCommands = (statingId, partnerId) => onCommand(statingId, command => {
     command.pairedWith = assignReference(partnerId);
 });
+/**
+ * Withdraws the pairing the command states.
+ * @category Operations
+ */
 export const unpairCommand = (statingId) => onCommand(statingId, command => {
     delete command.pairedWith;
 });

package/lib/ops/copies.d.ts

@@ -12,12 +12,14 @@ import { EditionOp } from "./draft.js";
  * inserts every symbol the copy's own tracker bar reads on it. The
  * version is a reading in that system's words, so it is coded for the
  * system the copy was cut for.
+ * @category Operations
  */
 export declare const createVersion: (copy: RollCopy) => EditionOp;
 /**
  * Puts the copy into the edition without a version of its own, as for a
  * copy whose features are not read into symbols: one known only from a
  * recording states instead which versions it carries.
+ * @category Operations
  */
 export declare const addCopy: (copy: RollCopy) => EditionOp;
 /**
@@ -26,6 +28,7 @@ export declare const addCopy: (copy: RollCopy) => EditionOp;
  * copy, or where the copy is the reference itself. The copy is read at
  * its own places whatever alignment it has, and through its own bar,
  * which is what lets a copy cut for another system be aligned at all.
+ * @category Operations
  */
 export declare const alignmentFor: (edition: Edition, copy: RollCopy, date?: Date) => Alignment | undefined;
 /**
@@ -34,12 +37,14 @@ export declare const alignmentFor: (edition: Edition, copy: RollCopy, date?: Dat
  * its features and tears onto the axis by them, in place of any
  * alignment it had. A copy that shares no run of notes with the
  * reference copy is left as it was.
+ * @category Operations
  */
 export declare const alignCopy: (copyId: string, date?: Date) => EditionOp;
 /**
  * Aligns every copy that has features with the reference copy, as
  * `alignCopy` does one. The reference copy itself is taken off any
  * alignment it had, its places being the axis.
+ * @category Operations
  */
 export declare const alignCopies: (date?: Date) => EditionOp;
 /**
@@ -47,27 +52,42 @@ export declare const alignCopies: (date?: Date) => EditionOp;
  * aligns every other copy onto it. Every place the edition gives along
  * the roll moves with this, which is why it is a choice and not
  * something worked out.
+ * @category Operations
  */
 export declare const chooseReferenceCopy: (copyId: string, date?: Date) => EditionOp;
 /**
  * Puts the copy's features back where they were measured, off the
  * axis. What the alignments say about the paper goes with it, since
  * that is worked out from them.
+ * @category Operations
  */
 export declare const unalignCopy: (copyId: string) => EditionOp;
 /**
  * Takes the extension a pneumatic reader adds off the ends of the
  * copy's chains of holes, and records how much was taken, so that their lengths
  * can be compared with a scanned copy's at all.
+ * @category Operations
  */
 export declare const shortenCopy: (copyId: string, extension: Millimeters, leaving?: ReadonlySet<string>) => EditionOp;
-/** Puts the reader's extension back on the copy's chains of holes. */
+/**
+ * Puts the reader's extension back on the copy's chains of holes.
+ * @category Operations
+ */
 export declare const unshortenCopy: (copyId: string) => EditionOp;
-/** States what the copy's features were read from, in place of any earlier statement. */
+/**
+ * States what the copy's features were read from, in place of any earlier statement.
+ * @category Operations
+ */
 export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
-/** Takes back the statement, leaving the copy silent about its source again. */
+/**
+ * Takes back the statement, leaving the copy silent about its source again.
+ * @category Operations
+ */
 export declare const clearSource: (copyId: string) => EditionOp;
-/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+/**
+ * Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank.
+ * @category Operations
+ */
 export declare const nameCopy: (copyId: string, siglum: string) => EditionOp;
 /** Takes out the copy's statements that match, and the list itself where none is left. */
 export declare const dropStatements: (copy: Draft<RollCopy>, matches: (statement: Readonly<ReferenceAssumption>) => boolean) => void;
@@ -77,15 +97,20 @@ export declare const dropStatements: (copy: Draft<RollCopy>, matches: (statement
  * one known only from a recording, and `carriageProblems` reports it
  * where features carry symbols already. A second statement about one
  * version is none.
+ * @category Operations
  */
 export declare const stateCarriage: (copyId: string, versionId: string, belief?: Belief) => EditionOp;
-/** Takes back the copy's statement that it carries the version. */
+/**
+ * Takes back the copy's statement that it carries the version.
+ * @category Operations
+ */
 export declare const clearCarriage: (copyId: string, versionId: string) => EditionOp;
 /**
  * Adds a general condition to the copy, beside whatever is stated of it
  * already. A paper stretch is added the same way, where one was
  * measured; what the alignments say of the paper is worked out from
  * them and stated nowhere.
+ * @category Operations
  */
 export declare const addGeneralCondition: (copyId: string, condition: ObjectAssumption<GeneralRollCondition>) => EditionOp;
 /**
@@ -93,19 +118,25 @@ export declare const addGeneralCondition: (copyId: string, condition: ObjectAssu
  * what was stated before; given nothing, it takes the statement away. A
  * copy has one paper, so it has one such condition, which may give a
  * strain in either direction.
+ * @category Operations
  */
 export declare const statePaperStretch: (copyId: string, stretch?: ObjectAssumption<PaperStretch>) => EditionOp;
 /**
  * Adds a tear to the copy, beside whatever is stated of it already. The
  * tear is given on the axis, where the copy's features stand, and moves
  * with them from then on.
+ * @category Operations
  */
 export declare const addTear: (copyId: string, tear: ObjectAssumption<Tear>) => EditionOp;
-/** The symbols of the versions that no other copy carries. */
+/**
+ * The symbols of the versions that no other copy carries.
+ * @category Operations
+ */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
 /**
  * Takes the copy out of the edition together with the symbols only it
  * carries, and with every reference the versions and the argumentations
  * made to those symbols.
+ * @category Operations
  */
 export declare const removeCopy: (copyId: string) => EditionOp;

package/lib/ops/copies.js

@@ -13,6 +13,7 @@ import { featureIdsOf, carriedOnlyOn, forgetFeatures } from "./forget.js";
  * inserts every symbol the copy's own tracker bar reads on it. The
  * version is a reading in that system's words, so it is coded for the
  * system the copy was cut for.
+ * @category Operations
  */
 export const createVersion = (copy) => draft => {
     const bar = barOf(copy);
@@ -28,6 +29,7 @@ export const createVersion = (copy) => draft => {
  * Puts the copy into the edition without a version of its own, as for a
  * copy whose features are not read into symbols: one known only from a
  * recording states instead which versions it carries.
+ * @category Operations
  */
 export const addCopy = (copy) => draft => {
     draft.copies.push(copy);
@@ -38,6 +40,7 @@ export const addCopy = (copy) => draft => {
  * copy, or where the copy is the reference itself. The copy is read at
  * its own places whatever alignment it has, and through its own bar,
  * which is what lets a copy cut for another system be aligned at all.
+ * @category Operations
  */
 export const alignmentFor = (edition, copy, date = new Date()) => {
     const reference = referenceCopyOf(edition);
@@ -62,6 +65,7 @@ export const alignmentFor = (edition, copy, date = new Date()) => {
  * its features and tears onto the axis by them, in place of any
  * alignment it had. A copy that shares no run of notes with the
  * reference copy is left as it was.
+ * @category Operations
  */
 export const alignCopy = (copyId, date = new Date()) => draft => {
     const state = stateOf(draft);
@@ -75,6 +79,7 @@ export const alignCopy = (copyId, date = new Date()) => draft => {
  * Aligns every copy that has features with the reference copy, as
  * `alignCopy` does one. The reference copy itself is taken off any
  * alignment it had, its places being the axis.
+ * @category Operations
  */
 export const alignCopies = (date = new Date()) => draft => {
     const reference = referenceCopyOf(stateOf(draft));
@@ -100,6 +105,7 @@ export const alignCopies = (date = new Date()) => draft => {
  * aligns every other copy onto it. Every place the edition gives along
  * the roll moves with this, which is why it is a choice and not
  * something worked out.
+ * @category Operations
  */
 export const chooseReferenceCopy = (copyId, date = new Date()) => draft => {
     if (!draft.copies.some(copy => copy.id === copyId))
@@ -111,6 +117,7 @@ export const chooseReferenceCopy = (copyId, date = new Date()) => draft => {
  * Puts the copy's features back where they were measured, off the
  * axis. What the alignments say about the paper goes with it, since
  * that is worked out from them.
+ * @category Operations
  */
 export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertAlignment(copy);
@@ -119,19 +126,32 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
  * Takes the extension a pneumatic reader adds off the ends of the
  * copy's chains of holes, and records how much was taken, so that their lengths
  * can be compared with a scanned copy's at all.
+ * @category Operations
  */
 export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenChains(extension, copy, leaving));
-/** Puts the reader's extension back on the copy's chains of holes. */
+/**
+ * Puts the reader's extension back on the copy's chains of holes.
+ * @category Operations
+ */
 export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
-/** States what the copy's features were read from, in place of any earlier statement. */
+/**
+ * States what the copy's features were read from, in place of any earlier statement.
+ * @category Operations
+ */
 export const stateSource = (copyId, source) => onCopy(copyId, copy => {
     copy.readFrom = source;
 });
-/** Takes back the statement, leaving the copy silent about its source again. */
+/**
+ * Takes back the statement, leaving the copy silent about its source again.
+ * @category Operations
+ */
 export const clearSource = (copyId) => onCopy(copyId, copy => {
     copy.readFrom = undefined;
 });
-/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+/**
+ * Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank.
+ * @category Operations
+ */
 export const nameCopy = (copyId, siglum) => onCopy(copyId, copy => {
     const trimmed = siglum.trim();
     if (trimmed)
@@ -156,6 +176,7 @@ export const dropStatements = (copy, matches) => {
  * one known only from a recording, and `carriageProblems` reports it
  * where features carry symbols already. A second statement about one
  * version is none.
+ * @category Operations
  */
 export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy => {
     const statements = stateOf(copy).carries ?? [];
@@ -163,13 +184,17 @@ export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy
         return;
     copy.carries = [...statements, referenceHeld(versionId, belief)];
 });
-/** Takes back the copy's statement that it carries the version. */
+/**
+ * Takes back the copy's statement that it carries the version.
+ * @category Operations
+ */
 export const clearCarriage = (copyId, versionId) => onCopy(copyId, copy => dropStatements(copy, statement => idOf(statement) === versionId));
 /**
  * Adds a general condition to the copy, beside whatever is stated of it
  * already. A paper stretch is added the same way, where one was
  * measured; what the alignments say of the paper is worked out from
  * them and stated nowhere.
+ * @category Operations
  */
 export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy => {
     copy.conditions.push(condition);
@@ -179,6 +204,7 @@ export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy =>
  * what was stated before; given nothing, it takes the statement away. A
  * copy has one paper, so it has one such condition, which may give a
  * strain in either direction.
+ * @category Operations
  */
 export const statePaperStretch = (copyId, stretch) => onCopy(copyId, copy => {
     copy.conditions = [...without(copy.conditions, isPaperStretch), ...(stretch ? [stretch] : [])];
@@ -187,11 +213,15 @@ export const statePaperStretch = (copyId, stretch) => onCopy(copyId, copy => {
  * Adds a tear to the copy, beside whatever is stated of it already. The
  * tear is given on the axis, where the copy's features stand, and moves
  * with them from then on.
+ * @category Operations
  */
 export const addTear = (copyId, tear) => onCopy(copyId, copy => {
     copy.conditions.push(tear);
 });
-/** The symbols of the versions that no other copy carries. */
+/**
+ * The symbols of the versions that no other copy carries.
+ * @category Operations
+ */
 export const symbolsCarriedOnlyBy = (edition, copyId) => {
     const copy = edition.copies.find(c => c.id === copyId);
     return copy ? insertedIn(edition.versions).filter(carriedOnlyOn(featureIdsOf(copy))) : [];
@@ -200,6 +230,7 @@ export const symbolsCarriedOnlyBy = (edition, copyId) => {
  * Takes the copy out of the edition together with the symbols only it
  * carries, and with every reference the versions and the argumentations
  * made to those symbols.
+ * @category Operations
  */
 export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
     forgetFeatures(draft, featureIdsOf(copy));

package/lib/ops/draft.d.ts

@@ -15,6 +15,7 @@ import { WithId } from "../shared/utils.js";
  * (`reading`) and does all its writing in the one function it builds
  * from that. Where operations run one after another on one draft, each
  * reads what the ones before it wrote.
+ * @category Operations
  */
 export type EditionOp = (draft: Draft<Edition>) => void;
 export declare const noChange: EditionOp;
@@ -33,6 +34,7 @@ export declare const reading: (build: (edition: Edition) => EditionOp) => Editio
  * The state a draft stands at, as plain data. Reading a draft proxies
  * everything it touches, so what is only read is read from this, and
  * what is looked up in an edition is looked up in this (`takenOf`).
+ * @category Lookups
  */
 export declare const stateOf: <T>(draft: Draft<T>) => T;
 /** The ids of the items the rewriting left out. */

package/lib/ops/draft.js

@@ -35,6 +35,7 @@ export const reading = (build) => draft => build(stateOf(draft))(draft);
  * The state a draft stands at, as plain data. Reading a draft proxies
  * everything it touches, so what is only read is read from this, and
  * what is looked up in an edition is looked up in this (`takenOf`).
+ * @category Lookups
  */
 export const stateOf = (draft) => isDraft(draft) ? takenOf(draft) : draft;
 /** The ids of the items the rewriting left out. */

package/lib/ops/edits.d.ts

@@ -3,7 +3,11 @@ import { EditionOp } from "./draft.js";
 /**
  * Replaces the edits with a single one carrying all their insertions
  * and deletions, classified by a guess at what the exchange does.
+ * @category Operations
  */
 export declare const mergeEdits: (versionId: string, toMerge: readonly Edit[]) => EditionOp;
-/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+/**
+ * Replaces the edit with one edit per inserted and one per deleted symbol.
+ * @category Operations
+ */
 export declare const splitEdit: (versionId: string, toSplit: Edit) => EditionOp;

package/lib/ops/edits.js

@@ -63,6 +63,7 @@ const guessEditType = (edition, versionId, edit) => {
 /**
  * Replaces the edits with a single one carrying all their insertions
  * and deletions, classified by a guess at what the exchange does.
+ * @category Operations
  */
 export const mergeEdits = (versionId, toMerge) => reading(edition => {
     if (toMerge.length === 0)
@@ -79,7 +80,10 @@ export const mergeEdits = (versionId, toMerge) => reading(edition => {
         version.edits = [...editsOf(version).filter(edit => !mergedIds.has(edit.id)), merged];
     });
 });
-/** Replaces the edit with one edit per inserted and one per deleted symbol. */
+/**
+ * Replaces the edit with one edit per inserted and one per deleted symbol.
+ * @category Operations
+ */
 export const splitEdit = (versionId, toSplit) => {
     const parts = [
         ...(toSplit.insert ?? []).map(insertion),

package/lib/ops/features.d.ts

@@ -6,6 +6,7 @@ import { EditionOp } from "./draft.js";
  * States the condition of the feature, in place of any earlier
  * statement. Throws where the kind of feature is in no such condition;
  * `conditions` says which conditions each kind of feature may be in.
+ * @category Operations
  */
 export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
 /**
@@ -13,6 +14,7 @@ export declare const stateFeatureCondition: (copyId: string, featureId: string,
  * copy, the act that brought another feature about, or, where neither
  * is said, an act of its own for the purpose given. A patch is never
  * punched, being glued on, so `punched` says nothing of one.
+ * @category Operations
  */
 export interface FeatureAct {
     /** The copy came from its punching with it, which is where a reading of a scan puts every chain of holes. */
@@ -28,12 +30,14 @@ export interface FeatureAct {
  * produced, by the punching or by a later act. Which act, `FeatureAct`
  * says; a `beside` that names nothing the copy bears is passed over and
  * the feature goes into an act of its own.
+ * @category Operations
  */
 export declare const addFeature: (copyId: string, feature: FeatureOrPatch, act?: FeatureAct) => EditionOp;
 /**
  * States that the patch bears the feature. What a patch bears came onto
  * the copy with the patch, so it belongs to no act of its own and
  * states no place: it stands where the patch stands.
+ * @category Operations
  */
 export declare const addBorneFeature: (copyId: string, patchId: string, feature: NestedFeature) => EditionOp;
 /**
@@ -42,9 +46,13 @@ export declare const addBorneFeature: (copyId: string, patchId: string, feature:
  * a patch goes with everything glued onto it, and a feature of a patch
  * may be taken back on its own, the patch staying where it is. An act
  * left having produced or added nothing goes as well.
+ * @category Operations
  */
 export declare const removeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
-/** Why several features cannot be replaced by one. */
+/**
+ * Why several features cannot be replaced by one.
+ * @category Operations
+ */
 export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features' | 'different-acts';
 /**
  * What stands in the way of reading the features as one, or nothing
@@ -53,6 +61,7 @@ export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tr
  * condition at most one of them states. How far apart they lie is not
  * asked: whether a gap is a bridge of the perforator, a tear or two
  * perforations of their own is the editor's reading.
+ * @category Operations
  */
 export declare const mergeObstacle: (features: readonly FeatureOrPatch[]) => MergeObstacle | undefined;
 /**
@@ -61,6 +70,7 @@ export declare const mergeObstacle: (features: readonly FeatureOrPatch[]) => Mer
  * features themselves say, which cannot reach `different-acts`: one
  * feature is the work of one act, and where the features stand is the
  * edition's business rather than theirs.
+ * @category Operations
  */
 export declare const mergeObstacleIn: (edition: Edition, featureIds: readonly string[]) => MergeObstacle | undefined;
 /**
@@ -80,5 +90,6 @@ export declare const mergeObstacleIn: (edition: Edition, featureIds: readonly st
  *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
+ * @category Operations
  */
 export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;

package/lib/ops/features.js

@@ -20,6 +20,7 @@ const allows = (feature, condition) => {
  * States the condition of the feature, in place of any earlier
  * statement. Throws where the kind of feature is in no such condition;
  * `conditions` says which conditions each kind of feature may be in.
+ * @category Operations
  */
 export const stateFeatureCondition = (copyId, featureId, condition) => onFeature(copyId, featureId, feature => {
     if (!allows(feature, condition)) {
@@ -108,6 +109,7 @@ const actFor = (copy, patch, act) => {
  * produced, by the punching or by a later act. Which act, `FeatureAct`
  * says; a `beside` that names nothing the copy bears is passed over and
  * the feature goes into an act of its own.
+ * @category Operations
  */
 export const addFeature = (copyId, feature, act = {}) => onCopy(copyId, copy => {
     actFor(copy, isPatch(feature), act).push(feature);
@@ -116,6 +118,7 @@ export const addFeature = (copyId, feature, act = {}) => onCopy(copyId, copy =>
  * States that the patch bears the feature. What a patch bears came onto
  * the copy with the patch, so it belongs to no act of its own and
  * states no place: it stands where the patch stands.
+ * @category Operations
  */
 export const addBorneFeature = (copyId, patchId, feature) => onCopy(copyId, copy => {
     const patch = featuresOf(copy).flatMap(withBorneFeatures).find(borne => borne.id === patchId);
@@ -131,6 +134,7 @@ export const addBorneFeature = (copyId, patchId, feature) => onCopy(copyId, copy
  * a patch goes with everything glued onto it, and a feature of a patch
  * may be taken back on its own, the patch staying where it is. An act
  * left having produced or added nothing goes as well.
+ * @category Operations
  */
 export const removeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
     const named = new Set(featureIds);
@@ -172,6 +176,7 @@ const conditionsOf = (features) => features.flatMap(feature => feature.condition
  * condition at most one of them states. How far apart they lie is not
  * asked: whether a gap is a bridge of the perforator, a tear or two
  * perforations of their own is the editor's reading.
+ * @category Operations
  */
 export const mergeObstacle = (features) => {
     if (features.length < 2)
@@ -209,6 +214,7 @@ const obstacleIn = (copy, featureIds) => {
  * features themselves say, which cannot reach `different-acts`: one
  * feature is the work of one act, and where the features stand is the
  * edition's business rather than theirs.
+ * @category Operations
  */
 export const mergeObstacleIn = (edition, featureIds) => {
     const copy = featureIds.map(id => copyOfFeature(edition, id)).find(copy => copy !== undefined);
@@ -277,6 +283,7 @@ const carryOver = (draft, replaced, mergedId) => {
  *
  * Throws where the features cannot stand for one; `mergeObstacle`
  * says beforehand whether they can.
+ * @category Operations
  */
 export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
     const state = stateOf(copy);

package/lib/ops/versions.d.ts

@@ -7,17 +7,25 @@ export declare const hypothesesBeside: (version: Readonly<Version>, parentId: st
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,
  * with the motivations that belonged to them.
+ * @category Operations
  */
 export declare const detachVersion: (versionId: string) => EditionOp;
 /**
  * Takes the version out. Whatever read its text against it comes to
  * stand on its own, a hypothesis that something derives from it goes,
  * and so does a copy's statement that it carries the version.
+ * @category Operations
  */
 export declare const removeVersion: (versionId: string) => EditionOp;
-/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+/**
+ * Takes the symbols out of the version's own insertions, and the edits that had nothing else.
+ * @category Operations
+ */
 export declare const removeSymbols: (versionId: string, symbolIds: readonly string[]) => EditionOp;
-/** Moves the edits into a new version based on this one. */
+/**
+ * Moves the edits into a new version based on this one.
+ * @category Operations
+ */
 export declare const deriveVersion: (versionId: string, editIds: readonly string[]) => EditionOp;
 /**
  * States that the version may also derive from the parent, beside what
@@ -26,7 +34,11 @@ export declare const deriveVersion: (versionId: string, editIds: readonly string
  * unless the belief holds this one more certain. A version derives from
  * itself, twice from one parent, or from one of its own descendants in
  * no statement.
+ * @category Operations
  */
 export declare const stateDerivation: (versionId: string, parentId: string, belief?: Belief) => EditionOp;
-/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+/**
+ * Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`.
+ * @category Operations
+ */
 export declare const clearDerivation: (versionId: string, parentId: string) => EditionOp;