Skip to content

feat(document-api): add 'story' targeting for parts targeting with main api functions #2477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
harbournick merged 8 commits into from
Mar 20, 2026
Merged

feat(document-api): add 'story' targeting for parts targeting with main api functions #2477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8f0f1da
feat(document-api): add story targeting and runtime support for non-b…
harbournick Mar 19, 2026
4df11e8
fix(presentation): refresh header/footer layout after doc-api slot cr…
harbournick Mar 19, 2026
761cbe5
chore: add doc api story test
harbournick Mar 19, 2026
e65f19d
fix: test suite bootstrap regressions and layout test timeouts
harbournick Mar 19, 2026
fa351bf
fix(document-api): invalidate stale header/footer story runtimes on p…
harbournick Mar 20, 2026
84ff738
fix(super-editor): avoid eager story-runtime imports in story editor …
harbournick Mar 20, 2026
34670ad
fix: make story-aware refs, ranges, and writes route correctly
harbournick Mar 20, 2026
835f707
fix(document-api): preserve story context and stabilize header/footer…
harbournick Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/docs/document-api/reference/_generated-manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -986,5 +986,5 @@
}
],
"marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
"sourceHash": "34852ca3a36fdbc4e68902541e89a9602b49b5031aacef23008f9c1f8d3f4677"
"sourceHash": "4b45100573fb74d1eb2f006d5064fbcc2e5af3331272207dccbab5f0c97142ef"
}
16 changes: 14 additions & 2 deletions apps/docs/document-api/reference/create/heading.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Returns a CreateHeadingResult with the new heading block ID and address.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after") |
| `in` | StoryLocator | no | StoryLocator |
| `level` | integer | yes | |
| `text` | string | no | |

Expand All @@ -39,8 +40,11 @@ Returns a CreateHeadingResult with the new heading block ID and address.
"at": {
"kind": "documentStart"
},
"level": 1,
"text": "Hello, world."
"in": {
"kind": "story",
"storyType": "body"
},
"level": 1
}
```

Expand Down Expand Up @@ -107,6 +111,11 @@ Returns a CreateHeadingResult with the new heading block ID and address.
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `AMBIGUOUS_TARGET`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down Expand Up @@ -180,6 +189,9 @@ Returns a CreateHeadingResult with the new heading block ID and address.
}
]
},
"in": {
"$ref": "#/$defs/StoryLocator"
},
"level": {
"description": "Heading level (1-6).",
"maximum": 6,
Expand Down
16 changes: 14 additions & 2 deletions apps/docs/document-api/reference/create/image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Returns a CreateImageResult with the new image address.
| --- | --- | --- | --- |
| `alt` | string | no | |
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") \\| object(kind="inParagraph") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after"), object(kind="inParagraph") |
| `in` | StoryLocator | no | StoryLocator |
| `size` | object | no | |
| `size.height` | number | no | |
| `size.width` | number | no | |
Expand All @@ -41,8 +42,11 @@ Returns a CreateImageResult with the new image address.
```json
{
"alt": "example",
"src": "example",
"title": "example"
"in": {
"kind": "story",
"storyType": "body"
},
"src": "example"
}
```

Expand All @@ -69,6 +73,11 @@ Returns a CreateImageResult with the new image address.
- `INVALID_TARGET`
- `CAPABILITY_UNAVAILABLE`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down Expand Up @@ -164,6 +173,9 @@ Returns a CreateImageResult with the new image address.
}
]
},
"in": {
"$ref": "#/$defs/StoryLocator"
},
"size": {
"additionalProperties": false,
"properties": {
Expand Down
14 changes: 13 additions & 1 deletion apps/docs/document-api/reference/create/paragraph.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `at` | object(kind="documentStart") \\| object(kind="documentEnd") \\| object(kind="before") \\| object(kind="after") | no | One of: object(kind="documentStart"), object(kind="documentEnd"), object(kind="before"), object(kind="after") |
| `in` | StoryLocator | no | StoryLocator |
| `text` | string | no | |

### Example request
Expand All @@ -38,7 +39,10 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
"at": {
"kind": "documentStart"
},
"text": "Hello, world."
"in": {
"kind": "story",
"storyType": "body"
}
}
```

Expand Down Expand Up @@ -105,6 +109,11 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `AMBIGUOUS_TARGET`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down Expand Up @@ -178,6 +187,9 @@ Returns a CreateParagraphResult with the new paragraph block ID and address.
}
]
},
"in": {
"$ref": "#/$defs/StoryLocator"
},
"text": {
"description": "Paragraph text content.",
"type": "string"
Expand Down
17 changes: 17 additions & 0 deletions apps/docs/document-api/reference/delete.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `behavior` | DeleteBehavior | no | DeleteBehavior |
| `in` | StoryLocator | no | StoryLocator |
| `target` | SelectionTarget | yes | SelectionTarget |
| `target.end` | SelectionPoint | yes | SelectionPoint |
| `target.kind` | `"selection"` | yes | Constant: `"selection"` |
Expand All @@ -41,13 +42,18 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `behavior` | DeleteBehavior | no | DeleteBehavior |
| `in` | StoryLocator | no | StoryLocator |
| `ref` | string | yes | |

### Example request

```json
{
"behavior": "selection",
"in": {
"kind": "story",
"storyType": "body"
},
"target": {
"end": {
"blockId": "block-abc123",
Expand Down Expand Up @@ -191,6 +197,11 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand All @@ -209,6 +220,9 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
"$ref": "#/$defs/DeleteBehavior",
"description": "Delete behavior: 'selection' (default) or 'exact'."
},
"in": {
"$ref": "#/$defs/StoryLocator"
},
"target": {
"$ref": "#/$defs/SelectionTarget",
"description": "Selection target: {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}. Use 'ref' instead when you have a search result handle."
Expand All @@ -226,6 +240,9 @@ Returns a TextMutationReceipt with applied status; receipt reports NO_OP if the
"$ref": "#/$defs/DeleteBehavior",
"description": "Delete behavior: 'selection' (default) or 'exact'."
},
"in": {
"$ref": "#/$defs/StoryLocator"
},
"ref": {
"description": "Handle ref string from a superdoc_search result. Pass the handle.ref value directly (e.g. 'text:eyJ...'). Preferred over 'target' for inline formatting.",
"type": "string"
Expand Down
14 changes: 13 additions & 1 deletion apps/docs/document-api/reference/find.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `in` | StoryLocator | no | StoryLocator |
| `limit` | integer | no | |
| `offset` | integer | no | |
| `options` | object | no | |
Expand All @@ -44,7 +45,10 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item

```json
{
"limit": 50,
"in": {
"kind": "story",
"storyType": "body"
},
"select": {
"caseSensitive": true,
"mode": "contains",
Expand Down Expand Up @@ -94,6 +98,11 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
- `CAPABILITY_UNAVAILABLE`
- `INVALID_INPUT`
- `ADDRESS_STALE`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand All @@ -106,6 +115,9 @@ Returns an SDFindResult envelope (\{ total, limit, offset, items \}). Each item
{
"additionalProperties": false,
"properties": {
"in": {
"$ref": "#/$defs/StoryLocator"
},
"limit": {
"type": "integer"
},
Expand Down
17 changes: 17 additions & 0 deletions apps/docs/document-api/reference/format/apply.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `in` | StoryLocator | no | StoryLocator |
| `inline` | object | yes | |
| `inline.bCs` | boolean \\| null | no | One of: boolean, null |
| `inline.bold` | boolean \\| null | no | One of: boolean, null |
Expand Down Expand Up @@ -83,6 +84,7 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `in` | StoryLocator | no | StoryLocator |
| `inline` | object | yes | |
| `inline.bCs` | boolean \\| null | no | One of: boolean, null |
| `inline.bold` | boolean \\| null | no | One of: boolean, null |
Expand Down Expand Up @@ -133,6 +135,10 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe

```json
{
"in": {
"kind": "story",
"storyType": "body"
},
"inline": {
"bold": true,
"italic": true
Expand Down Expand Up @@ -280,6 +286,11 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand All @@ -294,6 +305,9 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
{
"additionalProperties": false,
"properties": {
"in": {
"$ref": "#/$defs/StoryLocator"
},
"inline": {
"additionalProperties": false,
"description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold.",
Expand Down Expand Up @@ -1118,6 +1132,9 @@ Returns a TextMutationReceipt confirming inline styles were applied to the targe
{
"additionalProperties": false,
"properties": {
"in": {
"$ref": "#/$defs/StoryLocator"
},
"inline": {
"additionalProperties": false,
"description": "Inline formatting properties to apply. Set a property to apply it, use null to clear it. Example: {bold: true, italic: true} or {bold: null} to remove bold.",
Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/b-cs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/bold.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/border.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/caps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/char-scale.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/color.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/contextual-alternates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
5 changes: 5 additions & 0 deletions apps/docs/document-api/reference/format/cs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,11 @@ Returns a TextMutationReceipt confirming the inline run property patch was appli
- `CAPABILITY_UNAVAILABLE`
- `INVALID_TARGET`
- `INVALID_INPUT`
- `STORY_NOT_FOUND`
- `STORY_MISMATCH`
- `STORY_NOT_SUPPORTED`
- `CROSS_STORY_PLAN`
- `MATERIALIZATION_FAILED`

## Non-applied failure codes

Expand Down
Loading
Loading