@lincyaw/kernel 1.0.0-rc.27 → 1.0.0-rc.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincyaw/kernel",
3
- "version": "1.0.0-rc.27",
3
+ "version": "1.0.0-rc.28",
4
4
  "description": "Presmium's shared kernel: the IR and plugin contracts, the service registry, anchors and checks",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -199,6 +199,13 @@ export interface Production {
199
199
 
200
200
  /** A stable rich-text/code ID, or `page:${sectionId}` reserved for an existing section title. */
201
201
  export interface DocumentTextPoint { blockId: string, offset: number }
202
+ export interface DocumentTextAnchor { from: DocumentTextPoint, to: DocumentTextPoint }
203
+ /** A stable block, optionally at one step that renders it; the step belongs to the block's section. */
204
+ export interface DocumentPlaceAnchor { blockId: BlockId, stepId?: StepId }
205
+ export type DocumentThreadAnchor = DocumentTextAnchor | DocumentPlaceAnchor
206
+ /** A text range and a place are disjoint shapes; read the shape instead of guessing from offsets. */
207
+ export const isDocumentTextAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentTextAnchor => Boolean(anchor && 'from' in anchor && 'to' in anchor)
208
+ export const isDocumentPlaceAnchor = (anchor: DocumentThreadAnchor | undefined): anchor is DocumentPlaceAnchor => Boolean(anchor && 'blockId' in anchor && !('from' in anchor))
202
209
  export interface DocumentComment {
203
210
  id: string
204
211
  type: 'comment'
@@ -220,7 +227,7 @@ export interface DocumentThread {
220
227
  resolvedBy?: string
221
228
  metadata?: JsonObject
222
229
  deletedAt?: string
223
- anchor?: { from: DocumentTextPoint, to: DocumentTextPoint }
230
+ anchor?: DocumentThreadAnchor
224
231
  comments: DocumentComment[]
225
232
  }
226
233
 
@@ -1,6 +1,7 @@
1
1
  import { applyDocumentCaptionTiming } from './document-caption-timings.ts'
2
2
  import { hasRole } from './access.ts'
3
- import { applyDocumentCommentAction, DocumentCommentError, validateDocumentCommentAnchor } from './document-comments.ts'
3
+ import { applyDocumentCommentAction, degradeDocumentCommentAnchor, DocumentCommentError, validateDocumentCommentAnchor } from './document-comments.ts'
4
+ import { documentAnchorKey } from './document-places.ts'
4
5
  import { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange } from './document-voices.ts'
5
6
  import { applyDocumentComponentAction } from './document-components.ts'
6
7
  import type { DocumentAuthoringAction, DocumentAuthoringActionEffect } from './contracts/authoring-actions.ts'
@@ -29,17 +30,20 @@ export function applyDocumentAuthoringAction(document: TeachingDocument, action:
29
30
  return { content, effect: { kind: 'voice', scope: action.scope.kind, value: previewDocumentVoiceChange(document, action.scope, action.source, { replaceOverrides: action.replaceOverrides }), recordings } }
30
31
  }
31
32
  if (action.type === 'comment.create') validateDocumentCommentAnchor(document, action.anchor ?? undefined)
32
- let source = document.comments ?? {}, detached = false
33
+ let source = document.comments ?? {}, detached = false, degraded = false
33
34
  if (action.type !== 'comment.create' && Object.hasOwn(source, action.threadId)) {
34
35
  const thread = source[action.threadId]!
35
- try { validateDocumentCommentAnchor(document, thread.anchor) } catch (error) {
36
- if (!(error instanceof DocumentCommentError) || error.status !== 422) throw error
36
+ const anchor = degradeDocumentCommentAnchor(document, thread.anchor)
37
+ if (thread.anchor && !anchor) {
37
38
  const { anchor: _anchor, ...unanchored } = thread
38
39
  source = { ...source, [thread.id]: unanchored }; detached = true
40
+ } else if (anchor && documentAnchorKey(anchor) !== documentAnchorKey(thread.anchor)) {
41
+ source = { ...source, [thread.id]: { ...thread, anchor } }; degraded = true
39
42
  }
40
43
  }
41
44
  const { threads, effect } = applyDocumentCommentAction(source, action, context)
42
45
  if (detached) { effect.anchorDetached = true; effect.changed = true }
46
+ else if (degraded) effect.changed = true
43
47
  const content = { ...document }
44
48
  if (Object.keys(threads).length) content.comments = threads
45
49
  else delete content.comments
@@ -1,6 +1,10 @@
1
1
  import { hasRole } from './access.ts'
2
2
  import type { DocumentCommentAction, DocumentCommentContext, DocumentCommentEffect } from './contracts/document-comments.ts'
3
- import type { DocumentComment, DocumentThread, InlineNode, JsonObject, ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
3
+ import { isDocumentPlaceAnchor, isDocumentTextAnchor } from './contracts/document.ts'
4
+ import { documentBlockSection, documentCommentTargets } from './document-places.ts'
5
+ import type { DocumentComment, DocumentThread, DocumentThreadAnchor, JsonObject, ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
6
+
7
+ export { documentCommentTargets, isDocumentTextLink } from './document-places.ts'
4
8
 
5
9
  export class DocumentCommentError extends Error {
6
10
  readonly status: number
@@ -8,45 +12,19 @@ export class DocumentCommentError extends Error {
8
12
  }
9
13
  function fail(status: number, code: string): never { throw new DocumentCommentError(status, code) }
10
14
 
11
- /** Canonical anchor v1 expands only nonempty styled-text links; other inline values are atoms. */
12
- export function isDocumentTextLink(node: InlineNode): node is Extract<InlineNode, { type: 'link' }> & { children: Extract<InlineNode, { type: 'text' | 'break' }>[] } {
13
- return node.type === 'link' && node.children.length > 0 && node.children.every(child => child.type === 'text' || child.type === 'break')
14
- }
15
- function inlineText(nodes: readonly InlineNode[]): string {
16
- return nodes.map(node => node.type === 'text' ? node.text : node.type === 'break' ? '\n' : isDocumentTextLink(node) ? inlineText(node.children) : '\uFFFC').join('')
17
- }
18
-
19
- /** Only addressable canonical text identities, in native document order; opaque data is never traversed. */
20
- export function documentCommentTargets(document: TeachingDocument): Map<string, { order: number, text: string }> {
21
- const targets = new Map<string, { order: number, text: string }>()
22
- const add = (id: string, text: string) => { targets.set(id, { order: targets.size, text }) }
23
- const rich = (node: RichTextNode): void => {
24
- if (node.type === 'paragraph' || node.type === 'heading') add(node.id, inlineText(node.children))
25
- else if (node.type === 'code') add(node.id, node.value)
26
- else if (node.type === 'list') for (const item of node.children) {
27
- const [first, ...rest] = item.children
28
- add(item.id, first?.type === 'paragraph' ? inlineText(first.children) : '')
29
- ;(first?.type === 'paragraph' ? rest : item.children).forEach(rich)
30
- }
31
- else if (node.type === 'blockquote') {
32
- const [first, ...rest] = node.children
33
- if (first?.type === 'paragraph') { add(node.id, inlineText(first.children)); rest.forEach(rich) }
34
- else node.children.forEach(rich)
35
- } else if (node.type === 'table') for (const row of node.children) for (const cell of row.children) add(cell.id, inlineText(cell.children))
36
- }
37
- const block = (id: string): void => {
38
- const value = document.blocks[id]
39
- if (value?.type === 'text') value.content.forEach(rich)
40
- else if (value?.type === 'code' && value.value !== undefined) add(id, value.value)
41
- else if (value?.type === 'container' || value?.type === 'component') value.children?.forEach(block)
42
- }
43
- for (const id of document.sectionOrder) { const page = document.sections[id]!; add(`page:${id}`, page.title); page.children.forEach(block) }
44
- return targets
45
- }
46
-
47
15
  /** No ordinal, offset clamping, surrogate splitting or guessed fallback identity. */
48
16
  export function validateDocumentCommentAnchor(document: TeachingDocument, anchor: DocumentThread['anchor']): void {
49
17
  if (!anchor) return
18
+ if (isDocumentPlaceAnchor(anchor)) {
19
+ if (!Object.hasOwn(document.blocks, anchor.blockId)) fail(422, 'comment-anchor-target-unavailable')
20
+ if (anchor.stepId !== undefined) {
21
+ const step = Object.hasOwn(document.steps, anchor.stepId) ? document.steps[anchor.stepId] : undefined
22
+ const section = step ? document.sections[step.sectionId] : undefined
23
+ if (!step || !section || !section.stepOrder.includes(anchor.stepId) || step.sectionId !== documentBlockSection(document, anchor.blockId)) fail(422, 'comment-anchor-target-unavailable')
24
+ }
25
+ return
26
+ }
27
+ if (!isDocumentTextAnchor(anchor)) fail(422, 'comment-anchor-target-unavailable')
50
28
  const targets = documentCommentTargets(document), a = targets.get(anchor.from.blockId), b = targets.get(anchor.to.blockId)
51
29
  if (!a || !b) fail(422, 'comment-anchor-target-unavailable')
52
30
  for (const [point, target] of [[anchor.from, a], [anchor.to, b]] as const) {
@@ -57,6 +35,21 @@ export function validateDocumentCommentAnchor(document: TeachingDocument, anchor
57
35
  if (a.order > b.order || a.order === b.order && anchor.from.offset >= anchor.to.offset) fail(422, 'comment-anchor-range-invalid')
58
36
  }
59
37
 
38
+ /**
39
+ * The strongest still-valid anchor. A place whose step no longer exists keeps the block; a missing block or an
40
+ * unmappable text range leaves the discussion explicitly unanchored rather than silently pointing elsewhere.
41
+ */
42
+ export function degradeDocumentCommentAnchor(document: TeachingDocument, anchor: DocumentThreadAnchor | undefined): DocumentThreadAnchor | undefined {
43
+ if (!anchor) return undefined
44
+ try { validateDocumentCommentAnchor(document, anchor); return anchor }
45
+ catch (error) { if (!(error instanceof DocumentCommentError) || error.status !== 422) throw error }
46
+ if (isDocumentPlaceAnchor(anchor) && anchor.stepId !== undefined && Object.hasOwn(document.blocks, anchor.blockId)) {
47
+ const place: DocumentThreadAnchor = { blockId: anchor.blockId }
48
+ try { validateDocumentCommentAnchor(document, place); return place } catch { /* The block itself is not addressable. */ }
49
+ }
50
+ return undefined
51
+ }
52
+
60
53
  /** Shared native/editor permissions: editors may delete any discussion, but edit their own comment; a document owner may manage earlier authors. */
61
54
  export function applyDocumentCommentAction(source: NonNullable<TeachingDocument['comments']>, action: DocumentCommentAction, context: DocumentCommentContext): { threads: NonNullable<TeachingDocument['comments']>, effect: DocumentCommentEffect } {
62
55
  const member = context.member
@@ -1,6 +1,7 @@
1
1
  import jsonPatch from 'fast-json-patch'
2
2
  import type { Operation } from 'fast-json-patch'
3
3
  import { validateDocument } from './document.ts'
4
+ import { documentBlockSection } from './document-places.ts'
4
5
  import { documentParameterAccess } from './parameters.ts'
5
6
  import { DOCUMENT_PARAMETER_MAX_CHANGES, DOCUMENT_PARAMETER_MAX_PATH_DEPTH } from './contracts/authoring-actions.ts'
6
7
  import type { DocumentComponentAction, DocumentComponentEffect, DocumentParameterChange } from './contracts/authoring-actions.ts'
@@ -26,18 +27,9 @@ function component(document: TeachingDocument, id: string): ComponentBlock {
26
27
  }
27
28
  export function documentComponentSection(document: TeachingDocument, blockId: string): string {
28
29
  component(document, blockId)
29
- for (const sectionId of document.sectionOrder) {
30
- const pending = [...document.sections[sectionId]!.children], seen = new Set<string>()
31
- while (pending.length) {
32
- const id = pending.pop()!
33
- if (id === blockId) return sectionId
34
- if (seen.has(id)) continue
35
- seen.add(id)
36
- const block = document.blocks[id]
37
- if (block?.type === 'container' || block?.type === 'component') pending.push(...block.children ?? [])
38
- }
39
- }
40
- return fail(422, 'component-block-owner-missing', { blockId })
30
+ const section = documentBlockSection(document, blockId)
31
+ if (!section) return fail(422, 'component-block-owner-missing', { blockId })
32
+ return section
41
33
  }
42
34
  function stepOf(document: TeachingDocument, stepId: string, sectionId: string) {
43
35
  const step = own(document.steps, stepId) ? document.steps[stepId] : undefined
@@ -1,3 +1,5 @@
1
+ import { isDocumentPlaceAnchor } from './contracts/document.ts'
2
+ import { degradeDocumentCommentAnchor } from './document-comments.ts'
1
3
  import type { DocumentBlock, DocumentEditOperation, TeachingDocument } from './contracts/document.ts'
2
4
 
3
5
  /** Operations describe author intent; the caller validates the resulting complete document before committing it. */
@@ -69,6 +71,14 @@ export function applyDocumentOperations(source: TeachingDocument, operations: re
69
71
  if (!targetSteps.has(value.id)) value.visuals = value.visuals.filter(visual => !moved.has(visual.blockId))
70
72
  else for (const id of moved) if (!value.visuals.some(visual => visual.blockId === id)) value.visuals.push({ blockId: id, visible: true })
71
73
  }
74
+ // A step belongs to one section; a place comment stays on the block when that step no longer renders it.
75
+ for (const thread of Object.values(document.comments ?? {})) {
76
+ const anchor = thread.anchor
77
+ if (!anchor || !isDocumentPlaceAnchor(anchor) || anchor.stepId === undefined || !moved.has(anchor.blockId)) continue
78
+ const degraded = degradeDocumentCommentAnchor(document, anchor)
79
+ if (degraded) thread.anchor = degraded
80
+ else delete thread.anchor
81
+ }
72
82
  break
73
83
  }
74
84
  case 'deleteBlock': {
@@ -82,7 +92,11 @@ export function applyDocumentOperations(source: TeachingDocument, operations: re
82
92
  }
83
93
  for (const id of removed) visit(block(id))
84
94
  // A deleted range becomes an unanchored thread; its discussion survives.
85
- for (const thread of Object.values(document.comments ?? {})) if (thread.anchor && (identities.has(thread.anchor.from.blockId) || identities.has(thread.anchor.to.blockId))) delete thread.anchor
95
+ for (const thread of Object.values(document.comments ?? {})) {
96
+ const anchor = thread.anchor
97
+ if (!anchor) continue
98
+ if (isDocumentPlaceAnchor(anchor) ? identities.has(anchor.blockId) : identities.has(anchor.from.blockId) || identities.has(anchor.to.blockId)) delete thread.anchor
99
+ }
86
100
  detach(operation.blockId)
87
101
  for (const id of removed) delete document.blocks[id]
88
102
  for (const value of Object.values(document.steps)) value.visuals = value.visuals.filter(visual => !removed.has(visual.blockId))
@@ -1,3 +1,4 @@
1
+ import { isDocumentPlaceAnchor } from './contracts/document.ts'
1
2
  import type { ListItemNode, RichTextNode, TableCellNode, TableRowNode, TeachingDocument } from './contracts/document.ts'
2
3
  import type { DocumentPageDeletionImpact, DocumentPageIds } from './contracts/authoring.ts'
3
4
  import type { PageDeletePlan } from './contracts/workspace.ts'
@@ -89,7 +90,13 @@ export function pageDeletionImpact(document: TeachingDocument, section: string):
89
90
  for (const id of blocks) { const block = document.blocks[id]; if (block?.type === 'text') block.content.forEach(rich) }
90
91
  return { sectionId: section, retainedEmpty: document.sectionOrder.length === 1, blocks: [...blocks], steps: [...steps], narrations: [...removed], retainedNarrations: [...candidates].filter(id => !removed.has(id)), cues,
91
92
  clips: document.production.mediaClips.filter(clip => steps.has(clip.attachment.stepId)).map(clip => clip.id),
92
- detachedComments: Object.values(document.comments ?? {}).filter(thread => thread.anchor && (targets.has(thread.anchor.from.blockId) || targets.has(thread.anchor.to.blockId))).map(thread => thread.id), references }
93
+ detachedComments: Object.values(document.comments ?? {}).filter(thread => {
94
+ const anchor = thread.anchor
95
+ if (!anchor) return false
96
+ return isDocumentPlaceAnchor(anchor)
97
+ ? targets.has(anchor.blockId) || Boolean(anchor.stepId && steps.has(anchor.stepId))
98
+ : targets.has(anchor.from.blockId) || targets.has(anchor.to.blockId)
99
+ }).map(thread => thread.id), references }
93
100
  }
94
101
 
95
102
  export function pageDeletion(document: TeachingDocument, directory: string, version: string, section: string): PageDeletePlan {
@@ -0,0 +1,92 @@
1
+ import { isDocumentPlaceAnchor, isDocumentTextAnchor } from './contracts/document.ts'
2
+ import type { DocumentThreadAnchor, InlineNode, RichTextNode, TeachingDocument } from './contracts/document.ts'
3
+
4
+ /** The stable places a discussion can point at, in document order. */
5
+ export interface DocumentPlacesVisitor {
6
+ /** A page title or a block. */
7
+ place(id: string): void
8
+ /** An addressable text identity: a rich-text node, a code block or a page title. */
9
+ text(id: string, text: string): void
10
+ }
11
+
12
+ /** Canonical anchor v1 expands only nonempty styled-text links; other inline values are atoms. */
13
+ export function isDocumentTextLink(node: InlineNode): node is Extract<InlineNode, { type: 'link' }> & { children: Extract<InlineNode, { type: 'text' | 'break' }>[] } {
14
+ return node.type === 'link' && node.children.length > 0 && node.children.every(child => child.type === 'text' || child.type === 'break')
15
+ }
16
+ function inlineText(nodes: readonly InlineNode[]): string {
17
+ return nodes.map(node => node.type === 'text' ? node.text : node.type === 'break' ? '\n' : isDocumentTextLink(node) ? inlineText(node.children) : '\uFFFC').join('')
18
+ }
19
+
20
+ /**
21
+ * One walk over the document's stable places. Only addressable canonical identities are visited; opaque plugin
22
+ * data is never traversed. A caller that only needs text targets can ignore `place`.
23
+ */
24
+ export function walkDocumentPlaces(document: TeachingDocument, visit: DocumentPlacesVisitor): void {
25
+ const rich = (node: RichTextNode): void => {
26
+ if (node.type === 'paragraph' || node.type === 'heading') visit.text(node.id, inlineText(node.children))
27
+ else if (node.type === 'code') visit.text(node.id, node.value)
28
+ else if (node.type === 'list') for (const item of node.children) {
29
+ const [first, ...rest] = item.children
30
+ visit.text(item.id, first?.type === 'paragraph' ? inlineText(first.children) : '')
31
+ ;(first?.type === 'paragraph' ? rest : item.children).forEach(rich)
32
+ }
33
+ else if (node.type === 'blockquote') {
34
+ const [first, ...rest] = node.children
35
+ if (first?.type === 'paragraph') { visit.text(node.id, inlineText(first.children)); rest.forEach(rich) }
36
+ else node.children.forEach(rich)
37
+ } else if (node.type === 'table') for (const row of node.children) for (const cell of row.children) visit.text(cell.id, inlineText(cell.children))
38
+ }
39
+ const block = (id: string): void => {
40
+ visit.place(id)
41
+ const value = document.blocks[id]
42
+ if (value?.type === 'text') value.content.forEach(rich)
43
+ else if (value?.type === 'code' && value.value !== undefined) visit.text(id, value.value)
44
+ else if (value?.type === 'container' || value?.type === 'component') value.children?.forEach(block)
45
+ }
46
+ for (const id of document.sectionOrder) {
47
+ const page = document.sections[id]
48
+ if (!page) continue
49
+ visit.place(`page:${id}`)
50
+ visit.text(`page:${id}`, page.title)
51
+ page.children.forEach(block)
52
+ }
53
+ }
54
+
55
+ /** Only addressable canonical text identities, in native document order; opaque data is never traversed. */
56
+ export function documentCommentTargets(document: TeachingDocument): Map<string, { order: number, text: string }> {
57
+ const targets = new Map<string, { order: number, text: string }>()
58
+ walkDocumentPlaces(document, { place() {}, text: (id, text) => { targets.set(id, { order: targets.size, text }) } })
59
+ return targets
60
+ }
61
+
62
+ /** Every anchorable place in document order: page titles, blocks and text identities on one scale. */
63
+ export function documentAnchorOrder(document: TeachingDocument): Map<string, number> {
64
+ const places = new Map<string, number>()
65
+ const add = (id: string) => { if (!places.has(id)) places.set(id, places.size) }
66
+ walkDocumentPlaces(document, { place: add, text: add })
67
+ return places
68
+ }
69
+
70
+ /** The section that owns a block, following container and component children. */
71
+ export function documentBlockSection(document: TeachingDocument, blockId: string): string | undefined {
72
+ for (const sectionId of document.sectionOrder) {
73
+ const pending = [...document.sections[sectionId]!.children], seen = new Set<string>()
74
+ while (pending.length) {
75
+ const id = pending.pop()!
76
+ if (id === blockId) return sectionId
77
+ if (seen.has(id)) continue
78
+ seen.add(id)
79
+ const block = document.blocks[id]
80
+ if (block?.type === 'container' || block?.type === 'component') pending.push(...block.children ?? [])
81
+ }
82
+ }
83
+ return undefined
84
+ }
85
+
86
+ /** A key-order independent identity for comparing a thread anchor with a draft target. */
87
+ export function documentAnchorKey(anchor: DocumentThreadAnchor | undefined): string | undefined {
88
+ if (!anchor) return undefined
89
+ if (isDocumentPlaceAnchor(anchor)) return JSON.stringify(['place', anchor.blockId, anchor.stepId ?? null])
90
+ if (!isDocumentTextAnchor(anchor)) return undefined
91
+ return JSON.stringify(['text', anchor.from.blockId, anchor.from.offset, anchor.to.blockId, anchor.to.offset])
92
+ }
@@ -80,6 +80,6 @@ export const DOCUMENT_JSON_SCHEMA: Schema = {
80
80
  Production: object({ defaults: ref('StepProduction'), sectionOverrides: record(ref('StepProduction')), stepOverrides: record(ref('StepProduction')), narrationOverrides: record(object({ narrationStart: { enum: ['with-animation', 'after-animation'] } })), cueTimings: record(object({ pauseMs: nonnegative })), captionTimings: record(ref('CaptionTiming')), mediaClips: list(ref('MediaClip')) }, ['defaults', 'stepOverrides', 'mediaClips']),
81
81
  TextPoint: object({ blockId: { type: 'string', minLength: 1, maxLength: 205 }, offset: integer }),
82
82
  Comment: object({ id, type: tag('comment'), userId: id, createdAt: string, updatedAt: string, deletedAt: string, content: list(ref('RichTextNode')), metadata: ref('JsonObject'), reactions: list(object({ emoji: string, createdAt: string, userIds: ids })) }, ['id', 'type', 'userId', 'createdAt', 'updatedAt', 'reactions']),
83
- Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: object({ from: ref('TextPoint'), to: ref('TextPoint') }), comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
83
+ Thread: object({ id, type: tag('thread'), createdAt: string, updatedAt: string, resolved: { type: 'boolean' }, resolvedUpdatedAt: string, resolvedBy: id, metadata: ref('JsonObject'), deletedAt: string, anchor: { oneOf: [object({ from: ref('TextPoint'), to: ref('TextPoint') }), object({ blockId: id, stepId: id }, ['blockId'])] }, comments: list(ref('Comment')) }, ['id', 'type', 'createdAt', 'updatedAt', 'resolved', 'comments']),
84
84
  },
85
85
  }
package/src/document.ts CHANGED
@@ -3,6 +3,8 @@ import { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
3
3
  import { isRecord } from './errors.ts'
4
4
  import { captionSourceFingerprint, captionTimingProblem, stepCaptionText } from './document-caption-timings.ts'
5
5
  import { validateDocumentParameters } from './parameters.ts'
6
+ import { isDocumentPlaceAnchor } from './contracts/document.ts'
7
+ import { documentBlockSection } from './document-places.ts'
6
8
  import type { DocumentIssue, DocumentValidation, RichTextNode, TeachingDocument } from './contracts/document.ts'
7
9
 
8
10
  export { DOCUMENT_JSON_SCHEMA } from './document-schema.ts'
@@ -240,7 +242,17 @@ export function validateDocument(value: unknown): DocumentValidation {
240
242
  const path = at('/comments', id)
241
243
  if (id !== thread.id) issue(`${path}/id`, 'id.key', 'A thread ID must match its map key.')
242
244
  identify(thread.id, `${path}/id`)
243
- for (const edge of ['from', 'to'] as const) if (thread.anchor && !textTargets.has(thread.anchor[edge].blockId)) issue(`${path}/anchor/${edge}/blockId`, 'comment.target', 'A comment anchor must name a stable rich-text node or section title.')
245
+ const anchor = thread.anchor
246
+ if (anchor && isDocumentPlaceAnchor(anchor)) {
247
+ if (!Object.hasOwn(doc.blocks, anchor.blockId)) issue(`${path}/anchor/blockId`, 'comment.target', 'A place comment must name an existing block.')
248
+ else if (anchor.stepId !== undefined) {
249
+ const step = Object.hasOwn(doc.steps, anchor.stepId) ? doc.steps[anchor.stepId] : undefined
250
+ const section = step ? doc.sections[step.sectionId] : undefined
251
+ if (!step || !section || !section.stepOrder.includes(anchor.stepId) || step.sectionId !== documentBlockSection(doc, anchor.blockId)) issue(`${path}/anchor/stepId`, 'comment.target', 'A place comment must name a step of the block\'s own section.')
252
+ }
253
+ } else if (anchor) {
254
+ for (const edge of ['from', 'to'] as const) if (!textTargets.has(anchor[edge].blockId)) issue(`${path}/anchor/${edge}/blockId`, 'comment.target', 'A comment anchor must name a stable rich-text node or section title.')
255
+ }
244
256
  for (const [index, comment] of thread.comments.entries()) {
245
257
  identify(comment.id, `${path}/comments/${index}/id`)
246
258
  comment.content?.forEach((node, child) => rich(node, `${path}/comments/${index}/content/${child}`, new Set()))
package/src/index.ts CHANGED
@@ -7,7 +7,8 @@ export { documentOutline, documentPart, DocumentReadError } from './document-rea
7
7
  export { changeDocumentVoice, documentVoiceStepIds, previewDocumentVoiceChange, resolveDocumentStepVoice } from './document-voices.ts'
8
8
  export { DOCUMENT_COLOR_NAMES, documentColorToken, documentColorValue } from './document-colors.ts'
9
9
  export type { DocumentColorKind, DocumentColorName } from './document-colors.ts'
10
- export { applyDocumentCommentAction, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
10
+ export { applyDocumentCommentAction, degradeDocumentCommentAnchor, isDocumentTextLink, documentCommentTargets, validateDocumentCommentAnchor, DocumentCommentError } from './document-comments.ts'
11
+ export { documentAnchorKey, documentAnchorOrder, documentBlockSection, walkDocumentPlaces } from './document-places.ts'
11
12
  export { applyDocumentAuthoringAction } from './document-authoring-actions.ts'
12
13
  export { applyDocumentComponentAction, effectiveComponentParameters, createDocumentParameterChanges, documentComponentSection, DocumentComponentError } from './document-components.ts'
13
14
  export type { DocumentStepVoice, DocumentVoiceImpact, DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
@@ -24,7 +24,7 @@ export const DOCUMENT_AUTHORING_ACTION_SCHEMA: Schema = {
24
24
  ...object({ id, source: DOCUMENT_PAGE_DUPLICATION_SCHEMA.properties.source as unknown as Schema, action: { $ref: '#/$defs/AuthoringAction' } }),
25
25
  $defs: { ...(structuredClone(DOCUMENT_JSON_SCHEMA) as Exclude<Schema, boolean>).$defs,
26
26
  AuthoringAction: { oneOf: [
27
- action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } })] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
27
+ action('comment.create', { content, anchor: { oneOf: [{ type: 'null' }, object({ from: { $ref: '#/$defs/TextPoint' }, to: { $ref: '#/$defs/TextPoint' } }), object({ blockId: id, stepId: id }, ['blockId'])] }, metadata, commentMetadata: metadata }, ['content', 'anchor']),
28
28
  action('comment.reply', { threadId: id, content, metadata }, ['threadId', 'content']),
29
29
  action('comment.update', { threadId: id, commentId: id, content, metadata }, ['threadId', 'commentId', 'content']),
30
30
  action('comment.react', { threadId: id, commentId: id, emoji: { type: 'string', minLength: 1, maxLength: 32 }, active: { type: 'boolean' } }),