@heroiclands/package-build 23.10.0 → 23.11.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @heroiclands/package-build
 
+## 23.11.0
+
+### Minor Changes
+
+- References to private notes and secret sections now conceal their labels on the web; authors can keep selected references visible.
+- Inline spoilers preserve formatted text across websites, Foundry journals and books.
+
 ## 23.10.0
 
 ### Minor Changes

package/docs/api.md

@@ -1474,6 +1474,15 @@ Wikilink resolution for the knowledgebase build. The same authored links the pac
 | `frontmatterWikilinks` | `function frontmatterWikilinks(fm)`       | {Array<{path: string, link: string}>} In reading order; `path` is the dotted key path of the offending value (`government.summary`, `aliases.1`). | Every wikilink authored inside a frontmatter value.                   |
 | `resolveWebWikilinks`  | `function resolveWebWikilinks(body, ctx)` | {string} The body with wikilinks rewritten.                                                                                                       | Rewrites the wikilinks in a markdown body as KB-local markdown links. |
 
+Both `resolveWebWikilinks` and Foundry's `convertWikilinks` derive reference
+spoilers from the resolved note audience and secret-anchor metadata. A trailing
+`{.show}` bypasses automatic spoiler wrapping, without changing destination
+access. A web destination excluded by audience retains its label without an
+href. Same-note secret anchors follow the same rule; a whole-note link to a
+public note does not inherit individual secret sections. See the
+[authoring contract](authoring/links-and-markup.md#references-to-secret-subjects)
+for surface presentation.
+
 ### `engine.contentTables`
 
 Prepared SQL content tables are expanded into Markdown before link resolution.
@@ -1602,8 +1611,8 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | Export                     | Signature                                                  | Returns                                                         | Use it when                                                                                       |
 | -------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `WIKILINK`                 | `const WIKILINK`                                           | —                                                               | A wikilink, as authored.                                                                          |
-| `parseWikilink`            | `function parseWikilink(rawInner)`                         | {ParsedWikilink} The parts, each trimmed.                       | Split a wikilink's interior into its parts.                                                       |
-| `readWikilink`             | `function readWikilink(inner, context)`                    | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                                       |
+| `parseWikilink`            | `function parseWikilink(rawInner, literal?)`               | {ParsedWikilink} The parts, each trimmed.                       | Split a wikilink's interior into its parts.                                                       |
+| `readWikilink`             | `function readWikilink(inner, context, literal?)`          | Typed target or literal target with diagnostic source.          | Parse a link target using complete builder Address context.                                       |
 | `authoredLabel`            | `authoredLabel({ display })`                               | {string\|null} The label, or `null` when there is none to show. | The label an author actually supplied, or `null` when they supplied none.                         |
 | `unlabelledLinkMessage`    | `function unlabelledLinkMessage(target)`                   | {string} The message, unpunctuated at the end as a finding is.  | What an author writing an unlabelled link is told, in one place.                                  |
 | `LINK_FINDING_REASONS`     | `const LINK_FINDING_REASONS`                               | —                                                               | Every way a link can fail, named once for all three resolvers.                                    |
@@ -1614,6 +1623,15 @@ What a `[[…]]` **is**, before anything decides where it points. One authored l
 | `isEventAnchor`            | `isEventAnchor(hit, anchor)`                               | {boolean} Whether it is an event.                               | Whether the anchor a wikilink names is one of its target's events, which a wikilink may not name. |
 | `isSamePage`               | `isSamePage({ target, anchor })`                           | {boolean} True when the link is same-page.                      | Whether a parsed link addresses a section of the page it is written on.                           |
 
+`parseWikilink` and `readWikilink` accept the complete matched `literal` to
+read a trailing attribute block into `attributes`; its `classes` include the
+explicit `.show` override.
+
+| Export              | Signature                                         | Returns   | Use it when                                                                                       |
+| ------------------- | ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
+| `secretDestination` | `secretDestination(destination, anchor?)`         | `boolean` | Read the resolved note's GM audience or the referenced anchor's secret metadata.                  |
+| `presentWikilink`   | `presentWikilink(reference, parsed, destination)` | `string`  | Wrap a rendered reference as an inline spoiler unless the parsed link explicitly carries `.show`. |
+
 ### `engine.siteIndex`
 
 **The address index a site build resolves its wikilinks against.**
@@ -2371,6 +2389,15 @@ The engine wildcard subpath also exposes the body parsers below. Their figure ex
 | `engine/content-poetry.mjs`  | `verseLines`, `poetryStanzas`, `inlineVerse`, `poetryMarkdown`, `scanPoetry`, `renderPoetry` | Read `poetry` code fences, validate authored metadata and tabs, and preserve relative indent levels and stanzas.                                                                                                                       |
 | `engine/content-spans.mjs`   | `spanMarkdownPlugin`, `scanSpans`, `renderSpans`                                             | Parse bracket spans after recognized links. The scanner returns spans, the exact `.name` inventory and located errors, retaining visible text and attribute positions; rendering preserves inline Markdown and permitted attributes.   |
 
+Inline `.secret` spans preserve their inline content, name classes and
+attributes. Site rendering uses a separate show/hide button and content span,
+so a link inside the content does not become a nested control. Foundry renders
+visible inline text with a **Secret:** label, without native secret-section
+concealment; book rendering uses static secret styling and the same label.
+`collectAnchors` includes `secret: true` on secret anchors for destination
+presentation. Block and heading secrecy retain their separate scope and
+Foundry permission handling.
+
 `scanFigures` retains `line` (1-based caption line), `bodyStart`/`bodyEnd` (0-based, exclusive-end target range), and `close` (last consumed target line), plus caption attributes, kind, label and number. Unnumbered captions have an empty label and consume no number. `collectAnchors` discovers heading, caption, div, poem and span identifiers; `markupAnchorFindings(body)` reports collisions involving non-page identifiers; Foundry maps non-page anchors to the actual containing page UUID. An unnumbered `ref` requires `form="title"` or `form="full"`.
 
 `engine/markup-validation.mjs` provides shared syntax validation:

package/docs/authoring/first-note.md

@@ -41,6 +41,16 @@ For optional writing suggestions, run `npx package-build prose lint assets/conte
 
 The full Address is `<package>-note-lore-harbor`; `<package>` comes from `contentPackage` in `package-build.config.yaml`. In another note, `[[lore-harbor|Harbor]]` links to it. `[[lore-harbor|]]` asks the renderer to use the target's current name. The pipe is required.
 
+Use another subject's full canonical name at its first prose mention, then
+plain text for later mentions and aliases. Keep a note's own subject in plain
+text. Link indexed subjects even when they are private: the destination's
+audience automatically makes the whole reference a spoiler. Add `.show` only
+to intentionally reveal the reference; it grants no access to the destination.
+For an unwritten subject, use a typed span such as
+`[Aldric Venn]{.name data-type="being/npc"}`. The
+[links and markup guide](links-and-markup.md#marking-names-in-prose) covers
+these rules and separate `[text]{.secret}` spoilers.
+
 ## Grow the note only when needed
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.

package/docs/authoring/frontmatter.md

@@ -25,7 +25,7 @@ data: {}
 
 `description` is the short page summary. `tags` hold draft state and descriptive labels. The note type's classification belongs in `subType` where it is declared. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
 
-Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Links from untagged notes to GM notes are errors; GM notes may link to one another.
+Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Any note can reference a GM note with an ordinary wikilink. The whole reference is automatically a spoiler; `.show` reveals only that reference, without changing the target's audience or permissions. See [references to secret subjects](links-and-markup.md#references-to-secret-subjects).
 
 The formatter keeps a collection on one line when the full line is under 100 characters. Longer collections use full YAML block form. Run `package-build format --write` to apply key order and collection formatting.
 

package/docs/authoring/links-and-markup.md

@@ -23,10 +23,48 @@ A link to a note tagged `draft` retains its target and carries a visible draft c
 
 An HTML comment is an aside to whoever reads the note next, and no surface shows one — the packs and the website emit it into the HTML, where it stays a comment, and a book leaves it out. Write a `markdownlint` pragma or a note about a quoted passage freely. A comment inside a fence or a code span is an example and is printed as written, and a comment that is never closed is an error.
 
+## References to secret subjects
+
+Use an ordinary wikilink for an indexed subject, including a GM-only note:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]
+```
+
+The renderer reads the destination's audience and conceals the entire reference,
+including its label, as a spoiler. Authors do not repeat that audience at each
+reference. A reference to a public subject stays visible. A link to an anchor inside secret content
+conceals its reference too, including a same-note `[[#anchor|label]]`.
+Linking to the public note as a whole does not inherit a section's secrecy.
+
+| Surface | Reference to a secret destination                                                                                                                                      |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Website | An inline show/hide spoiler conceals its label. An omitted GM-only destination produces text without an unusable link. A published secret heading can still be linked. |
+| Foundry | A visible inline spoiler labelled **Secret:** contains the reference. Private pack and page permissions govern whether its destination can be opened.                  |
+| Book    | The reference prints with secret styling and a **Secret:** label. An omitted GM-only destination produces text without a link.                                         |
+
+`.show` removes that automatic spoiler presentation on every surface. Where
+the target is unavailable it still produces text without a link.
+
+To intentionally reveal this reference, add `.show` immediately after the link:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]{.show}
+[[doc-magictruth|The Truth of Magic]]{.show}
+```
+
+`.show` reveals only this reference. It does not publish the destination, change
+its audience or grant Foundry access. It is redundant for a public target.
+Use `[text]{.secret}` when the text itself is a spoiler, independently of any
+destination; see [inline spoilers](#inline-spoilers).
+
 ## Marking names in prose
 
 Use `[Name]{.name}` for a name that has no indexed note. Link a name that has
-one; an empty link label uses the indexed full name. Bold is emphasis.
+one, including a private subject; an empty link label uses the indexed full
+name. Introduce another subject with its full canonical name at its first prose
+use. Keep the note's own subject in plain text, and use plain text for later
+mentions and aliases. Bold is emphasis.
 Plain text, including capitalized words, is not searched for names.
 
 ```markdown
@@ -39,7 +77,7 @@ creating a placeholder note:
 
 ```markdown
 [Ravenmoor]{.name data-type="place/settlement"}
-[Aldric Venn]{.name data-type="being"}
+[Aldric Venn]{.name data-type="being/npc"}
 ```
 
 `data-type` is optional. It names a declared [note type and
@@ -196,6 +234,38 @@ optional declared type; see [marking names](#marking-names-in-prose).
 
 Inline Markdown remains active inside the span. Bracket spans have lower priority than URL links, image links, reference links, footnotes and wikilinks. A bracketed form immediately preceded by `!`, followed by `(` or another `[`, or beginning with `[[` is not a span, even when the link is unresolved. Ordinary links retain their existing syntax. Escape a bracket when it should be literal, or put examples inside a code span or fence. A span identifier addresses that point in the note; it does not start a journal page.
 
+### Inline spoilers
+
+Mark text itself as a spoiler with `.secret`. It can contain inline Markdown or
+combine with a typed name for an unwritten subject:
+
+```markdown
+The key is [under the **third** stair]{.secret}.
+The informant is [Aldric Venn]{.name .secret data-type="being/npc"}.
+```
+
+This marks only the enclosed text; it does not declare a target's audience.
+For indexed subjects, use the ordinary wikilink and let the destination decide
+whether the reference needs a spoiler. `.show` on a wikilink bypasses automatic
+reference concealment; an enclosing authored `.secret` still marks its text.
+
+On the website an inline spoiler has a button to show or hide its content.
+It stays within the surrounding sentence, and links inside it can be followed
+after revealing it. Foundry prints a visible inline `secret` span labelled
+**Secret:**; this span does not withhold its text from players. The book prints
+the text with secret styling and a **Secret:** label; printed text cannot be
+interactively concealed.
+These presentations preserve inline emphasis and the `.name` classification.
+
+Published web HTML contains the spoiler's text. Revealing the spoiler or reading
+the page source exposes it; this is presentation, not access control. GM-only
+destination notes remain absent from public site and book output.
+
+A `.secret` span does not start a journal page or change surrounding text.
+Use a [secret heading](#a-section-players-must-not-read) to withhold a whole
+Foundry page or a [secret block](#secret-blocks) for a passage in a labelled
+section; those retain their own scope and presentation.
+
 ### Alerts
 
 Alerts replace the former `:::info` and `:::warn` fences. Start with a special blockquote marker, optionally followed by an attribute block, then write the alert body as a standard blockquote:
@@ -997,8 +1067,8 @@ common.
 
 Public dictionaries omit citations to GM-only notes. `links` checks generated
 tables in the source note's audience: public notes use public rows, and GM
-notes retain GM citations. An authored link from a public note to a GM-only
-note is still reported.
+notes retain GM citations. An authored wikilink from a public note to a GM-only
+note is valid and follows the [secret-reference rules](#references-to-secret-subjects).
 
 #### Custom views
 

package/docs/content-format.md

@@ -52,8 +52,10 @@ for examples and placement in journals, web pages, and books.
 An inline `{{sql "SELECT COUNT(*) FROM notes"}}` expression inserts one scalar query result. Use `{{words (sql "SELECT COUNT(*) FROM notes")}}` for a count in running prose, or `{{digits (sql "SELECT COUNT(*) FROM entries")}}` for grouped numerals. The query must return exactly one row and one column with a nonempty value; a mismatch is a located build error. Prefix `\{{` to show the syntax literally. The [expression reference](reference/format-details.md#dates-and-calendars) describes the helpers and the available SQL relations.
 
 Add `gm` to `tags` for a GM-only note. Public site and book builds omit it;
-Foundry compiles it only into private compendiums. An untagged note cannot link
-to it. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
+Foundry compiles it only into private compendiums. Ordinary wikilinks to it
+conceal the whole reference as a spoiler; `.show` reveals just the reference.
+`[text]{.secret}` marks text itself as a spoiler. Neither changes the target's
+access permissions. The [frontmatter guide](authoring/frontmatter.md#frontmatter-and-system-blocks)
 explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.

package/docs/design.md

@@ -21,6 +21,24 @@ An Address identifies a subject by package, system, type, and shortcode. It is i
 
 The content index uses JSON Lines. A record can retain the note's full frontmatter, anchors, and outgoing links, and streams without loading one giant JSON array. It is derived, disposable, and stable for a fixed source tree and toolchain version. SQL queries and editor navigation read that index rather than guessing from filenames.
 
+## Reference presentation and access
+
+An indexed subject has one ordinary wikilink syntax regardless of its audience.
+The renderer derives spoiler presentation from the actual destination, so an
+author does not duplicate a privacy declaration on every mention. The `.show`
+override reveals a particular reference without changing the destination's
+audience. A separate inline `.secret` span marks authored text as a spoiler.
+
+Concealment and access remain separate decisions. Public site and book builds
+omit GM-only notes; a reference to an omitted destination carries no unusable
+link. Foundry's private packs and page permissions govern destination access.
+Web inline spoilers use a separate show/hide control beside their content, so
+a revealed link is independently usable. Foundry and book inline spoilers are
+visible labelled text; an inline Foundry span has no native secret-section
+permission behavior. A spoiler in published HTML remains readable in the source. See the
+[authoring contract](authoring/links-and-markup.md#references-to-secret-subjects)
+for syntax and surface presentation.
+
 ## Build boundaries
 
 The content pass reads `assets/content/` and addressable assets. It emits the content index, page source, and Foundry documents. Site rendering and book typesetting consume those outputs; their layout decisions do not become fields of a Foundry DataModel. Packaging stages only the files a Foundry manifest declares. The build checks emitted fields against the target system schema because Foundry can otherwise discard an unknown field without an error.

package/docs/guides/book.md

@@ -522,6 +522,13 @@ Anchors on headings are scoped to their entries, so two entries can use the
 same heading anchor. The build reports an unresolved destination while
 keeping the source available for inspection.
 
+A reference to a GM-only note or secret heading prints with secret styling
+and a **Secret:** label. GM-only notes remain omitted, and references to them
+print as text without a link. `.show` removes the automatic spoiler presentation
+of that reference, without adding the destination to the book. An authored
+`[text]{.secret}` uses the same static inline styling. Printed text remains
+visible; see [secret references](../authoring/links-and-markup.md#references-to-secret-subjects).
+
 The [generated sections](../reference/format-details.md#generated-sections)
 an entry carries — **Within**, **Governed by**, **In song and story**, the
 event views and the rest — name notes the build chose rather than the author,

package/docs/guides/site.md

@@ -118,6 +118,13 @@ Wikilinks resolve through the address index. Each emitted page receives
 derived `related` entries for the links its author wrote and the backlinks
 other authors wrote to it.
 
+A wikilink to a GM-only note or secret heading conceals its whole reference in
+an inline show/hide spoiler. `.show` reveals the reference without changing the
+destination's audience. GM-only pages remain omitted, so references to them
+have no link; published secret sections retain theirs. Spoiler text remains in
+the generated HTML and is readable in page source. See
+[secret references](../authoring/links-and-markup.md#references-to-secret-subjects).
+
 What lies within a place, who governs it, what an affiliation governs, the
 works naming a note and the map from a place reach the page as
 [generated sections](../reference/format-details.md#generated-sections): H1

package/docs/reference/format-details.md

@@ -515,7 +515,10 @@ is declared, so a near miss is a finding that names what you probably meant.
 
 `gm` marks a note for GM access. It is excluded from public site pages, SQL
 tables on the public site, and the book. Foundry compiles it only to private
-compendiums. A regular note cannot link to it; a GM note can.
+compendiums. Any note may reference it with an ordinary wikilink; the
+reference is automatically a spoiler. The `.show` override reveals that
+reference without changing the destination's audience or access permissions;
+see [references to secret subjects](#references-to-secret-subjects).
 
 **`draft` marks unfinished content.** It does two things and nothing
 else: a link _into_ a draft note renders marked, and the note itself states that
@@ -1808,6 +1811,37 @@ name at every citation with no link edited. `[[x|]]` is labelled; `[[x]]` is not
 It is the label that is required, not a target: the anchor-only form above
 carries its pipe like every other link.
 
+#### References to secret subjects
+
+Use `[[doc-divineactn|The Truth of Divine Action]]` for an indexed subject,
+including one with a GM-only audience. The renderer derives spoiler presentation
+from the resolved destination and conceals the whole reference, including its
+label. A public destination has no automatic concealment. An anchor inside secret
+content is a secret destination, including a same-note anchor reference. A
+link to the whole public note does not inherit a section's secrecy.
+
+The website renders an inline show/hide spoiler; an omitted GM-only target
+retains its reference as text without a dead link. A published secret section
+retains its link. Foundry renders a visible inline spoiler with a **Secret:**
+label, with access to its destination controlled by private packs and page
+permissions. Books print secret styling and a **Secret:** label, retaining text
+without a link when the GM-only destination is omitted. `.show` bypasses the
+automatic spoiler presentation on each surface; an unavailable destination
+still has no link.
+
+An immediately following `.show` attribute explicitly reveals the reference:
+
+```markdown
+[[doc-divineactn|The Truth of Divine Action]]{.show}
+[[doc-magictruth|The Truth of Magic]]{.show}
+```
+
+This override changes the reference's presentation only. It does not publish a
+GM-only note, alter Foundry permissions or reveal the destination's content.
+It is redundant for public destinations. `[text]{.secret}` separately marks
+text itself as a spoiler; it declares no destination audience. See
+[inline spans](#inline-spans) for inline spoiler syntax and surface behavior.
+
 #### Marking names in prose
 
 `package-build lint` reports name-marking warnings in authored body prose.
@@ -1815,7 +1849,10 @@ The warnings leave a valid package passing. Headings, frontmatter, tables,
 infoboxes, code, comments and embeds are outside this check.
 
 A name is explicit: a `[Name]{.name}` bracket span or an authored link label.
-Use `.name` for names without indexed notes and links for names with notes.
+Use typed `.name` spans for unwritten subjects and ordinary wikilinks for
+indexed subjects, including private ones. Introduce another subject with its
+full canonical name at its first prose use; use plain text for the note's own
+subject and for later mentions and aliases.
 Plain prose is not searched for names. Wikilinks, ordinary Markdown links and
 reference links all supply names; a resolved empty wikilink label uses the
 note's full name. Images, code, footnote markers and bare autolinks without
@@ -1856,7 +1893,7 @@ An optional `data-type` on a `.name` span states what the named thing is:
 
 ```markdown
 [Ravenmoor]{.name data-type="place/settlement"}
-[Aldric Venn]{.name data-type="being"}
+[Aldric Venn]{.name data-type="being/npc"}
 ```
 
 Use a declared [note type](note-types.md), optionally followed by `/` and one
@@ -3483,6 +3520,25 @@ The watch wears [a _blue_ sash]{#watch-sash .uniform lang=en}.
 
 The exact `.name` class marks a name, with optional `data-type="type/subType"`;
 see [marking names in prose](#marking-names-in-prose) for the vocabulary and index.
+The exact `.secret` class marks the enclosed text as an inline spoiler:
+
+```markdown
+[The hidden **passage**]{.secret}
+[Aldric Venn]{.name .secret data-type="being/npc"}
+```
+
+The website provides an inline show/hide button and preserves interactive links
+inside the revealed content. Foundry prints a visible inline `secret` span
+with a **Secret:** label; the span does not withhold its text from players.
+The book prints the text with secret styling and a **Secret:** label.
+Inline emphasis and combined `.name` classification survive rendering. Published HTML retains the text, so opening
+the spoiler or inspecting the source reveals it.
+
+This span has no effect on a destination's audience. Ordinary wikilinks derive
+spoilers from their resolved destinations; `.show` bypasses that automatic
+concealment without cancelling an enclosing authored `.secret`. An inline span
+does not change the scope of `.secret` headings or `:::secret` blocks, and it
+does not start or withhold a JournalEntryPage.
 
 Inline Markdown remains active inside the span. Bracket spans have lower priority than URL links, image links, reference links, footnotes and wikilinks. A bracketed form immediately preceded by `!`, followed by `(` or another `[`, or beginning with `[[` is not a span, even when the link is unresolved. Ordinary links retain their existing syntax. Escape a bracket when it should be literal, or put examples inside a code span or fence. A span identifier addresses that point in the note; it does not start a journal page.
 

package/engine/anchors.mjs

@@ -41,7 +41,7 @@ import { scanPoetry } from "./content-poetry.mjs";
 import { scanSpans } from "./content-spans.mjs";
 import { slugify } from "./content-slug.mjs";
 import { scanFigures } from "./content-figures.mjs";
-import { scanHeadingAttributes } from "./heading-attributes.mjs";
+import { withheldSections, scanHeadingAttributes } from "./heading-attributes.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
 /**
@@ -67,11 +67,12 @@ export const ANCHOR_KINDS = Object.freeze(["prose", "event"]);
  *   {@link module:engine/content-figures.scanFigures}.
  * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{slug: string, name: string, level: number, line: number,
- *   kind: string}>} In document order.
+ *   kind: string, secret?: boolean}>} In document order.
  */
 export function collectAnchors(body, bodyLine = 1, resolveRole, syntax) {
     const anchors = [];
-    for (const heading of scanHeadingAttributes(body, bodyLine).headings) {
+    const headings = scanHeadingAttributes(body, bodyLine).headings;
+    for (const heading of headings) {
         if (!heading.id) continue;
         anchors.push({
             slug: heading.id,
@@ -91,9 +92,12 @@ export function collectAnchors(body, bodyLine = 1, resolveRole, syntax) {
             kind: "prose",
         });
     }
+    const secretBlocks = [];
     const blockAnchors = (source, firstLine) => {
         const sourceLines = source.split("\n");
         for (const block of (syntax ? syntax(source).blocks : scanBlocks(source)).blocks) {
+            if (block.name === "secret")
+                secretBlocks.push({ start: firstLine + block.start, end: firstLine + block.end });
             if (block.id)
                 anchors.push({
                     slug: slugify(block.id),
@@ -129,7 +133,8 @@ export function collectAnchors(body, bodyLine = 1, resolveRole, syntax) {
                 kind: "prose",
             });
     }
-    for (const span of (syntax ? syntax(body).spans : scanSpans(body)).spans) {
+    const spans = (syntax ? syntax(body).spans : scanSpans(body)).spans;
+    for (const span of spans) {
         if (span.id)
             anchors.push({
                 slug: slugify(span.id),
@@ -139,6 +144,33 @@ export function collectAnchors(body, bodyLine = 1, resolveRole, syntax) {
                 kind: "prose",
             });
     }
+    const sections =
+        headings.some((heading) => heading.classes.includes("secret")) ?
+            withheldSections(body).sections
+        :   [];
+    const secretSpans = spans.filter((span) =>
+        span.attrs.some(([key, value]) => key === "class" && value.split(/\s+/).includes("secret")),
+    );
+    const secretSpanAnchors = new Set(
+        spans
+            .filter(
+                (target) =>
+                    target.id &&
+                    secretSpans.some(
+                        (parent) => parent.start <= target.start && parent.end >= target.end,
+                    ),
+            )
+            .map((span) => span.id),
+    );
+    for (const anchor of anchors) {
+        const line = anchor.line - bodyLine;
+        if (
+            sections.some((section) => line >= section.start && line < section.end) ||
+            secretBlocks.some((block) => anchor.line >= block.start && anchor.line <= block.end) ||
+            secretSpanAnchors.has(anchor.slug)
+        )
+            anchor.secret = true;
+    }
     return anchors.sort((a, b) => a.line - b.line);
 }
 

package/engine/content-links.mjs

@@ -444,13 +444,17 @@ export function buildLinkIndex(
         // Code is verbatim, so a `[[…]]` inside a fence, an indented block or an
         // inline span is not a link — the compilers make none of it either.
         for (const [all, rawInner] of matchAllOutsideCode(body, new RegExp(WIKILINK.source, "g"))) {
-            const parsed = readWikilink(rawInner, {
-                package: pkg,
-                system: "note",
-                types,
-                packages,
-                noIndexPackages,
-            });
+            const parsed = readWikilink(
+                rawInner,
+                {
+                    package: pkg,
+                    system: "note",
+                    types,
+                    packages,
+                    noIndexPackages,
+                },
+                all,
+            );
             const target = parsed.target.kind ? parsed.rawTarget : parsed.target;
             const { anchor, rawTarget } = parsed;
             const occurrence = (seen.get(all) ?? 0) + 1;
@@ -459,6 +463,7 @@ export function buildLinkIndex(
             // in the file. A link a table generated is not in the file at all,
             // so the search simply fails and a finding names the file.
             out.push({
+                attributeProblems: parsed.attributes?.problems ?? [],
                 target,
                 rawTarget,
                 anchor,
@@ -962,15 +967,23 @@ export function auditLinks(index) {
 
     const deadAnchors = [];
     for (const note of notes) {
-        for (const { target, rawTarget, anchor, text, occurrence, labelled } of linksOf(note)) {
+        for (const {
+            target,
+            rawTarget,
+            anchor,
+            text,
+            occurrence,
+            labelled,
+            attributeProblems,
+        } of linksOf(note)) {
             if (!anchor || !labelled) continue;
             const local = target ? resolve(target) : note;
             const foreign = !local && target ? manifestHit(target) : null;
             // An unresolved address is reported below. A foreign sheet opens
             // its system document, so only the readable note view names prose
-            // sections. A public note's GM target is an audience refusal below.
+            // sections, including private destinations.
             if (!local) {
-                if (!foreign || (foreign.gm && !isGmNote(note.fm))) continue;
+                if (!foreign) continue;
                 const qualified = readQualifier(
                     target,
                     index.types,
@@ -1016,7 +1029,24 @@ export function auditLinks(index) {
     const unlabelledLinks = [];
     const usedManifest = new Set();
     for (const note of notes) {
-        for (const { target, rawTarget, anchor, text, occurrence, labelled } of linksOf(note)) {
+        for (const {
+            target,
+            rawTarget,
+            anchor,
+            text,
+            occurrence,
+            labelled,
+            attributeProblems,
+        } of linksOf(note)) {
+            if (attributeProblems.length)
+                deadAddresses.push({
+                    note,
+                    target: rawTarget,
+                    text,
+                    occurrence,
+                    reason: "invalid-attributes",
+                    problems: attributeProblems,
+                });
             // The label is required whatever the link part is, an anchor
             // included — so this is tested before the same-page form.
             if (!labelled) {
@@ -1063,9 +1093,6 @@ export function auditLinks(index) {
             }
             const resolved = index.resolveAddress(target);
             if (resolved) {
-                if ((isGmNote(resolved.fm) || resolved.gm) && !isGmNote(note.fm)) {
-                    deadAddresses.push({ ...at, reason: "gm" });
-                }
                 continue;
             }
             // A stub is in the index, so the refusal can name it. Asked before
@@ -1084,10 +1111,6 @@ export function auditLinks(index) {
             // report.
             const manifest = manifestHit(target);
             if (manifest) {
-                if (manifest.gm && !isGmNote(note.fm)) {
-                    deadAddresses.push({ ...at, reason: "gm" });
-                    continue;
-                }
                 usedManifest.add(encodeAddresses(target).toLowerCase());
                 continue;
             }

package/engine/content-spans.mjs

@@ -21,21 +21,41 @@ import { inlineText } from "./name-markup.mjs";
 
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
+ * @param {object} [options] - Surface presentation.
+ * @param {boolean} [options.spoilers] - Add visible static Secret labels (Foundry).
  */
-export function spanMarkdownPlugin(md) {
+export function spanMarkdownPlugin(md, { spoilers = false } = {}) {
+    if (spoilers) {
+        md.renderer.rules.span_open = (tokens, index, options, env, renderer) => {
+            const token = tokens[index];
+            const secret = (token.attrGet("class") ?? "").split(/\s+/).includes("secret");
+            return (
+                renderer.renderToken(tokens, index, options) +
+                (secret ? '<strong class="inline-secret-label">Secret:</strong> ' : "")
+            );
+        };
+    }
     md.inline.ruler.after("link", "bracket_span", (state, silent) => {
         const start = state.pos;
         if (
             state.src[start] !== "[" ||
+            // Raw wikilinks are handled before spans render. Refuse their
+            // adjacent closing brackets without parsing every label twice.
+            (state.src[start + 1] === "[" &&
+                state.src[state.src.indexOf("]", start + 2) + 1] === "]") ||
             /@[A-Za-z]+$/.test(state.src.slice(0, start)) ||
-            state.src[start + 1] === "[" ||
             state.src[start + 1] === "^" ||
             state.src[start + 1] === "!" ||
             ["!", "[", "]"].includes(state.src[start - 1])
         )
             return false;
         const end = state.md.helpers.parseLinkLabel(state, start, false);
-        if (end < 0 || ["(", "["].includes(state.src[end + 1])) return false;
+        if (
+            end < 0 ||
+            ["(", "["].includes(state.src[end + 1]) ||
+            (state.src[start + 1] === "[" && state.src[end + 1] !== "{")
+        )
+            return false;
         let finish = end + 1;
         let parsed = { id: "", classes: [], values: {}, problems: [] };
         if (state.src[finish] === "{") {
@@ -259,10 +279,15 @@ export function renderSpans(source) {
         )
         .sort((a, b) => b.start - a.start)) {
         const attrs = span.attrs.map(([key, value]) => ` ${key}="${escape(value)}"`).join("");
-        markdown =
-            markdown.slice(0, span.start) +
-            `<span${attrs}>${renderSpans(markdown.slice(span.start + 1, span.contentEnd)).markdown}</span>` +
-            markdown.slice(span.end);
+        const inner = renderSpans(markdown.slice(span.start + 1, span.contentEnd)).markdown;
+        const secret = span.attrs.some(
+            ([key, value]) => key === "class" && value.split(/\s+/).includes("secret"),
+        );
+        const content =
+            secret ?
+                `<span${attrs} data-inline-secret><button type="button" class="inline-secret-toggle" aria-label="Show spoiler" aria-expanded="false">Show spoiler</button><span class="inline-secret-content" hidden>${inner}</span></span>`
+            :   `<span${attrs}>${inner}</span>`;
+        markdown = markdown.slice(0, span.start) + content + markdown.slice(span.end);
     }
     return { markdown, errors };
 }

package/engine/helpers.mjs

@@ -70,7 +70,7 @@ import { buildWikilinkIndex, convertWikilinks } from "./wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // The declared tag vocabulary, which is where `draft` is stated. Read
 // from there rather than respelt, so the tag and its one reader cannot drift.
-import { isDraftNote } from "./note-vocabulary.mjs";
+import { isGmNote, isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { spanMarkdownPlugin } from "./content-spans.mjs";
@@ -108,7 +108,7 @@ let localAssetImageInfoCache;
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
-    .use(spanMarkdownPlugin)
+    .use(spanMarkdownPlugin, { spoilers: true })
     .use(dictionaryEntryPlugin)
     // A heading's attribute block, written onto the heading element rather than
     // typeset into it — the reading the website's renderer does for itself.
@@ -888,6 +888,8 @@ export function buildContentLinkIndex(
             // *into* this note renders marked. It takes no part in resolution,
             // so the note is indexed, compiled and published as any other.
             draft: isDraftNote(fm),
+            gm: isGmNote(fm),
+            noteAnchors: [...(record.anchors ?? []), ...(prepared?.anchors ?? [])],
             // The anchors this note declares, carried so the *builds* can check
             // a `#section` link and not only the checker. A foreign
             // anchor has always been checked, because a fetched index

package/engine/pdf-render.mjs

@@ -1630,7 +1630,7 @@ export function bookTypstPreamble() {
         // weight so it remains bold inside an ordinary strong phrase.
         "#let book-span(body, classes: ()) = {\n" +
             '  let styled = if classes.contains("name") { text(weight: "bold", body) } else { body }\n' +
-            "  box(styled)\n" +
+            '  if classes.contains("secret") { box(fill: rgb("#f2eefb"), inset: (x: 3pt, y: 1pt), text(fill: rgb("#5c4b8a"))[#strong[Secret:] #styled]) } else { box(styled) }\n' +
             "}",
         // Use the file's natural measure for auto. Every requested width is
         // bounded by the available measure and by the height of a page.

package/engine/site-index.mjs

@@ -70,7 +70,7 @@ import { contentPackage } from "./content-package.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { presentAmongRecords } from "./being-age.mjs";
 // The declared tag vocabulary, which is where `draft` is stated.
-import { isDraftNote } from "./note-vocabulary.mjs";
+import { isGmNote, isDraftNote } from "./note-vocabulary.mjs";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -219,6 +219,24 @@ export function buildSiteIndex(
     // a stale vendored manifest and a shadowed local page.
     const { ambiguous } = mergeForeign(index, foreignIndex);
 
+    // Private notes have no public page, but still resolve references safely.
+    for (const record of records) {
+        if (!isGmNote(record) || !record.address || !record.shortcode) continue;
+        contentTypes.add(record.type);
+        const value = {
+            name: record.name?.full ?? record.name,
+            gm: true,
+            noteAnchors: record.anchors ?? [],
+        };
+        index.set(`${record.type}/${record.shortcode}`.toLowerCase(), value);
+        const pkg = record.package ?? ownPackage;
+        index.set(
+            canonicalKey(pkg, ownDocumentSystem(record.type), record.type, record.shortcode),
+            value,
+        );
+        index.set(canonicalKey(pkg, "note", record.type, record.shortcode), value);
+    }
+
     for (const e of entries) {
         // Only a content note is addressable; anything else is carried
         // through and takes no part in type-scoped indexing.
@@ -233,19 +251,20 @@ export function buildSiteIndex(
         // `subType` is: a being states a rank as a number, and what that
         // number is called is declared on the body.
         const standings = standingsDigest(e.fm);
+        const noteAnchors = collectAnchors(e.body ?? "", 1, undefined, syntax);
         const value = {
             url: e.url,
             name: e.name,
             draft: isDraftNote(e.fm),
+            gm: isGmNote(e.fm),
+            noteAnchors,
             ...(e.fm.subType ? { subType: e.fm.subType } : {}),
             ...(standings ? { standings } : {}),
             // The `{#anchor}` slugs this page declares, so a `#section`
             // written against it can be checked rather than joined onto the
             // URL unverified. A Set even when empty: a page that declares no
             // anchor still has a definite answer for one an author names.
-            anchors: new Set(
-                collectAnchors(e.body ?? "", 1, undefined, syntax).map((anchor) => anchor.slug),
-            ),
+            anchors: new Set(noteAnchors.map((anchor) => anchor.slug)),
             // The note's event ids, which a wikilink may not name.
             eventAnchors: new Set(eventAnchors(e.fm).map((anchor) => anchor.slug)),
         };

package/engine/web-wikilinks.mjs

@@ -41,7 +41,8 @@
 // cannot drift apart on it: they disagreed once over the unlabelled hyphen
 // form, which the packs showed as a raw shortcode and the knowledgebase as a
 // name.
-import { readWikilink } from "./wikilink-syntax.mjs";
+import { collectAnchors } from "./anchors.mjs";
+import { presentWikilink, readWikilink } from "./wikilink-syntax.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-system-type-shortcode` key, so a package-qualified
@@ -354,6 +355,7 @@ export function resolveWebWikilinks(body, ctx) {
     // same counting the checker does, and what turns a finding into a
     // `file:line:column:` diagnostic rather than a note-wide one.
     const seen = new Map();
+    let ownAnchors = ctx.noteAnchors;
     /**
      * Records a finding against one authored literal.
      *
@@ -404,18 +406,28 @@ export function resolveWebWikilinks(body, ctx) {
     // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
     // inline span is source text, not a link.
     return replaceOutsideCode(embedded.markdown, WIKILINK, (all, rawInner) => {
-        const parsed = readWikilink(rawInner, {
-            package: ctx.contentPackage,
-            system: "note",
-            types: ctx.contentTypes ?? new Set(),
-            packages: ctx.packages,
-            noIndexPackages: ctx.noIndexPackages,
-        });
+        const parsed = readWikilink(
+            rawInner,
+            {
+                package: ctx.contentPackage,
+                system: "note",
+                types: ctx.contentTypes ?? new Set(),
+                packages: ctx.packages,
+                noIndexPackages: ctx.noIndexPackages,
+            },
+            all,
+        );
         const { rawTarget: target, anchor, display } = parsed;
         // An empty label is not a label: `[[x|]]` addresses the target and
         // shows its name, so `""` falls through to the same place `null` does.
         // One reading, from {@link authoredLabel}.
         const label = authoredLabel({ display });
+        if (parsed.attributes?.problems.length)
+            return report(
+                all,
+                { target, reason: "invalid-attributes", problems: parsed.attributes.problems },
+                label ?? target,
+            );
 
         // **Every link carries a label**. Without one there is nothing
         // to resolve against, and nothing to show either, a shortcode being an
@@ -445,7 +457,11 @@ export function resolveWebWikilinks(body, ctx) {
                     label ?? anchor,
                 );
             }
-            return `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`;
+            return presentWikilink(
+                `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`,
+                parsed,
+                { noteAnchors: (ownAnchors ??= collectAnchors(body)) },
+            );
         }
 
         // The canonical separator has to be resolved, not merely
@@ -480,7 +496,7 @@ export function resolveWebWikilinks(body, ctx) {
                     label ?? hit.name ?? target,
                 );
             }
-            if (anchor && hit.url && !hasAnchor(hit.noteAnchors ?? hit.anchors, anchor)) {
+            if (anchor && !hasAnchor(hit.noteAnchors ?? hit.anchors, anchor)) {
                 return report(
                     all,
                     { target, reason: "unknown-anchor", anchor, addressed: true },
@@ -506,8 +522,13 @@ export function resolveWebWikilinks(body, ctx) {
             // Presentation only — the href above is unchanged, and a
             // `[[#anchor]]` self-link is not marked because the reader is
             // already on the page it would be telling them about.
-            if (!hit.draft) return link;
-            return ctx.output === "book" ? `${link} (draft)` : draftLink(link);
+            return presentWikilink(
+                !hit.draft ? link
+                : ctx.output === "book" ? `${link} (draft)`
+                : draftLink(link),
+                parsed,
+                hit,
+            );
         }
 
         // **An address resolving nowhere is a failure, unconditionally**.

package/engine/wikilink-syntax.mjs

@@ -11,6 +11,9 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import { isGmNote } from "./note-vocabulary.mjs";
+
 import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
 
 /**
@@ -67,7 +70,7 @@ import { parseAddress, isAddressTuple, splitAnchor } from "./address.mjs";
  * copies of the exclusion is three places for it to be forgotten. An embed's
  * own grammar is {@link module:engine/content-embeds}.
  */
-export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\]/g;
+export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\](?:\{(?:[^{}"\n]|"(?:\\.|[^"\\\n])*")*\})?/g;
 
 /**
  * The parts of a wikilink's interior.
@@ -80,6 +83,7 @@ export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\]/g;
  * @property {string} anchor - The `#section` slug, `""` when there is none.
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+ * @property {ReturnType<typeof parseExtensionAttributes>} [attributes] - Trailing extension attributes.
  * @property {boolean} labelled - Whether a `|` was present at all. A link
  *   without one addresses nothing and is a finding — see
  *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
@@ -92,9 +96,10 @@ export const WIKILINK = /(?<!!)\[\[([^\]\n]+)\]\]/g;
  * not the whole link, so a caller that has already matched does not re-match.
  *
  * @param {string} rawInner - The text between `[[` and `]]`.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {ParsedWikilink} The parts, each trimmed.
  */
-export function parseWikilink(rawInner) {
+export function parseWikilink(rawInner, literal = "") {
     // A pipe inside a markdown table cell is escaped as `\|`; undo that before
     // looking for the label separator, or the cell's own escape reads as one.
     const inner = String(rawInner ?? "").replace(/\\\|/g, "|");
@@ -108,7 +113,18 @@ export function parseWikilink(rawInner) {
     // link and a field cannot disagree about where the anchor starts.
     const { address: target, anchor = "" } = splitAnchor(linkPart);
 
-    return { inner: inner.trim(), target, anchor, display, labelled };
+    const suffix = literal.slice(literal.indexOf("]]") + 2);
+    const attributes =
+        suffix.startsWith("{") ? parseExtensionAttributes(suffix.slice(1, -1)) : null;
+    if (attributes) attributes.problems.push(...refusedAttributes(attributes.values));
+    return {
+        inner: inner.trim(),
+        target,
+        anchor,
+        display,
+        labelled,
+        ...(attributes ? { attributes } : {}),
+    };
 }
 
 /**
@@ -193,6 +209,7 @@ export function unlabelledLinkMessage(target) {
  */
 export const LINK_FINDING_REASONS = Object.freeze(
     new Set([
+        "invalid-attributes",
         "unlabelled",
         "not-an-address",
         "not-lowercase",
@@ -201,7 +218,6 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "not-an-asset",
         "unresolved",
         "stub",
-        "gm",
         "ambiguous",
         "unknown-anchor",
         "event-anchor",
@@ -323,6 +339,7 @@ export function ambiguousAddressMessage(target, packages = []) {
  * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
  *   shortcode as written.
+ * @param {string[]} [finding.problems] - Invalid attribute diagnostics.
  * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
  *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
@@ -338,8 +355,11 @@ export function linkFindingMessage({
     stub,
     shortcode,
     declared,
+    problems,
 }) {
     switch (reason) {
+        case "invalid-attributes":
+            return `wikilink [[${target}]] has invalid attributes: ${(problems ?? []).join("; ")}`;
         case "unlabelled":
             return unlabelledLinkMessage(target);
         case "not-an-address":
@@ -386,8 +406,6 @@ export function linkFindingMessage({
             return unresolvedAddressMessage(target);
         case "stub":
             return stubAddressMessage(target, stub);
-        case "gm":
-            return `address [[${target}]] names a GM-only note from a player-facing note`;
         case "no-content-index":
             return (
                 `address [[${target}]] names a package declared \`contentIndex: false\` — ` +
@@ -419,10 +437,11 @@ export function isSamePage({ target, anchor }) {
  * Read an operational link target in its enclosing Address context.
  * @param {string} inner - Lexical link contents.
  * @param {object} context - Builder defaults and type vocabulary.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {object} Typed target and diagnostic source spelling.
  */
-export function readWikilink(inner, context) {
-    const parsed = parseWikilink(inner);
+export function readWikilink(inner, context, literal = "") {
+    const parsed = parseWikilink(inner, literal);
     const rawTarget = parsed.target;
     if (!rawTarget) return { ...parsed, rawTarget, target: { kind: "same-page" } };
     const target = parseAddress(rawTarget, context);
@@ -433,3 +452,41 @@ export function readWikilink(inner, context) {
             { ...parsed, rawTarget, target: { kind: "literal", text: rawTarget }, problem: target }
         :   { ...parsed, rawTarget, target };
 }
+
+/** Whether the actual referenced destination needs spoiler presentation.
+ * @param {object} destination - Resolved note metadata.
+ * @param {string} [anchor] - Referenced prose anchor.
+ * @returns {boolean} Whole-note or section audience.
+ */
+export function secretDestination(destination, anchor = "") {
+    return Boolean(
+        destination?.gm ||
+        isGmNote(destination?.fm ?? destination) ||
+        (anchor && destination?.noteAnchors?.some((one) => one.slug === anchor && one.secret)),
+    );
+}
+
+/** Apply destination-derived presentation without changing its address.
+ * @param {string} reference - Rendered reference Markdown.
+ * @param {object} parsed - Shared parsed wikilink.
+ * @param {object} destination - Resolved target metadata.
+ * @returns {string} Inline spoiler or visible reference.
+ */
+export function presentWikilink(reference, parsed, destination) {
+    const attrs = parsed.attributes;
+    const classes = (attrs?.classes ?? []).filter((value) => value !== "show");
+    if (
+        !attrs?.classes.includes("show") &&
+        secretDestination(destination, parsed.anchor) &&
+        !classes.includes("secret")
+    )
+        classes.push("secret");
+    const fields = [
+        attrs?.id ? `#${attrs.id}` : "",
+        ...classes.map((value) => `.${value}`),
+        ...Object.entries(attrs?.values ?? {}).map(
+            ([key, value]) => `${key}="${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`,
+        ),
+    ].filter(Boolean);
+    return fields.length ? `[${reference}]{${fields.join(" ")}}` : reference;
+}

package/engine/wikilinks.mjs

@@ -27,7 +27,7 @@
 
 import { resolveShortcodeReference } from "./shortcode-references.mjs";
 
-import { readWikilink } from "./wikilink-syntax.mjs";
+import { presentWikilink, readWikilink } from "./wikilink-syntax.mjs";
 import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
@@ -407,15 +407,29 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
     // one capture group. It is what makes two identical unresolved links on
     // one note tellable apart, and a position reportable at all.
     const out = replaceOutsideCode(markdown, WIKILINK, (all, rawInner, offset) => {
-        const parsed = readWikilink(rawInner, {
-            package: index.contentPackage,
-            system: "note",
-            types: index.types,
-            packages: index.packages,
-            noIndexPackages: index.noIndexPackages,
-        });
+        const parsed = readWikilink(
+            rawInner,
+            {
+                package: index.contentPackage,
+                system: "note",
+                types: index.types,
+                packages: index.packages,
+                noIndexPackages: index.noIndexPackages,
+            },
+            all,
+        );
         const target = parsed.rawTarget;
         const slug = parsed.anchor || null;
+        if (parsed.attributes?.problems.length) {
+            unresolved.push({
+                link: all,
+                target,
+                offset,
+                reason: "invalid-attributes",
+                problems: parsed.attributes.problems,
+            });
+            return unresolvedLink(authoredLabel(parsed) ?? target, target);
+        }
 
         // **Every link carries a label**. Without one there is nothing
         // to resolve against: a shortcode is an address rather than prose, so
@@ -512,7 +526,11 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
             if (hit) {
                 const uuid = slug ? hit.anchors?.[slug] : hit.uuid;
                 if (uuid) {
-                    return `@UUID[${uuid}]{${text || hit.name || target}}`;
+                    return presentWikilink(
+                        `@UUID[${uuid}]{${text || hit.name || target}}`,
+                        parsed,
+                        hit,
+                    );
                 }
                 unresolved.push({
                     link: all,
@@ -559,7 +577,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
         const entryUuid = itemDoc ? addresses.docUuid : addresses.uuid;
         // The target has no single Foundry document. Its address is real, but
         // a compendium has nothing to open, so the reader gets the label.
-        if (entryUuid === undefined) return text;
+        if (entryUuid === undefined) return presentWikilink(text, parsed, doc);
         const entryId = itemDoc ? itemDocEntryId(doc.id) : doc.id;
         const isJournal = itemDoc || packForType(doc.type).docType === "JournalEntry";
         // A JournalEntry link opens a journal — at its first page, or at the
@@ -614,7 +632,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index, cap
         // Presentation only — the UUID above is unchanged, and a
         // `[[#slug]]` self-link is not marked because the reader is already in
         // the note it would be telling them about.
-        return doc.draft ? draftLink(link) : link;
+        return presentWikilink(doc.draft ? draftLink(link) : link, parsed, doc);
     });
 
     return { markdown: out, unresolved };

package/hugo-theme/layouts/partials/footer.html

@@ -27,3 +27,5 @@ document.querySelector('.nav-toggle')?.addEventListener('click', function() {
   this.classList.toggle('open');
 });
 </script>
+
+<script src="{{ "js/inline-spoilers.js" | relURL }}" defer></script>

package/hugo-theme/static/css/style.css

@@ -2992,3 +2992,19 @@ summary.info-sidebar-title::after {
 .single-content .alert-warning {
   --pb-alert-color: #d29922;
 }
+
+/* Inline spoiler controls remain inline, with links outside the button. */
+[data-inline-secret] .inline-secret-content[hidden] { display: none !important; }
+.inline-secret-toggle {
+    display: inline;
+    padding: 0.05em 0.35em;
+    border: 1px solid currentColor;
+    border-radius: 0.2em;
+    color: inherit;
+    background: transparent;
+    font: inherit;
+    font-size: 0.85em;
+    cursor: pointer;
+}
+.inline-secret-toggle:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+.inline-secret-content { margin-inline-start: 0.25em; }

package/hugo-theme/static/js/inline-spoilers.js

@@ -0,0 +1,23 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// A native button provides pointer, Enter and Space activation without taking
+// keyboard events away from links within the independently revealed content.
+document.addEventListener("click", (event) => {
+    const button = event.target.closest?.(".inline-secret-toggle");
+    if (!button) return;
+    const wrapper = button.parentElement;
+    const content = button.nextElementSibling;
+    if (!wrapper?.hasAttribute("data-inline-secret") || !content?.classList.contains("inline-secret-content")) return;
+    const expanded = button.getAttribute("aria-expanded") !== "true";
+    if (!expanded && content.contains(document.activeElement)) button.focus();
+    content.hidden = !expanded;
+    button.setAttribute("aria-expanded", String(expanded));
+    const label = expanded ? "Hide spoiler" : "Show spoiler";
+    button.setAttribute("aria-label", label);
+    button.textContent = label;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.10.0",
+    "version": "23.11.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/anchors.d.mts

@@ -14,7 +14,7 @@
  *   {@link module:engine/content-figures.scanFigures}.
  * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
  * @returns {Array<{slug: string, name: string, level: number, line: number,
- *   kind: string}>} In document order.
+ *   kind: string, secret?: boolean}>} In document order.
  */
 export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (address: string) => string | undefined, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
     slug: string;
@@ -22,6 +22,7 @@ export function collectAnchors(body: string, bodyLine?: number, resolveRole?: (a
     level: number;
     line: number;
     kind: string;
+    secret?: boolean;
 }>;
 /** Collisions involving a div, verse or inline-span anchor.
  * Heading and caption collisions are diagnosed by their existing scanners.

package/types/engine/content-spans.d.mts

@@ -1,7 +1,11 @@
 /** Add bracket spans after recognized Markdown links and footnotes.
  * @param {import("markdown-it")} md - Markdown parser to extend.
+ * @param {object} [options] - Surface presentation.
+ * @param {boolean} [options.spoilers] - Add visible static Secret labels (Foundry).
  */
-export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
+export function spanMarkdownPlugin(md: typeof import("markdown-it"), { spoilers }?: {
+    spoilers?: boolean | undefined;
+}): void;
 /** Read span anchors and located attribute diagnostics outside literal code.
  * @param {string} source - Authored Markdown.
  * @returns {import("./name-markup.mjs").SpanScan} Actual spans, explicit names and located diagnostics.

package/types/engine/wikilink-syntax.d.mts

@@ -9,6 +9,7 @@
  * @property {string} anchor - The `#section` slug, `""` when there is none.
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
+ * @property {ReturnType<typeof parseExtensionAttributes>} [attributes] - Trailing extension attributes.
  * @property {boolean} labelled - Whether a `|` was present at all. A link
  *   without one addresses nothing and is a finding — see
  *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
@@ -20,9 +21,10 @@
  * not the whole link, so a caller that has already matched does not re-match.
  *
  * @param {string} rawInner - The text between `[[` and `]]`.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {ParsedWikilink} The parts, each trimmed.
  */
-export function parseWikilink(rawInner: string): ParsedWikilink;
+export function parseWikilink(rawInner: string, literal?: string): ParsedWikilink;
 /**
  * The label an author actually supplied, or `null` when they supplied none.
  *
@@ -158,13 +160,14 @@ export function ambiguousAddressMessage(target: string, packages?: Iterable<stri
  * @param {string} [finding.stub] - For `stub`, where the stub is.
  * @param {string} [finding.shortcode] - For `shortcode-not-lowercase`, the
  *   shortcode as written.
+ * @param {string[]} [finding.problems] - Invalid attribute diagnostics.
  * @param {string} [finding.declared] - For `shortcode-not-lowercase`, the
  *   lowercase spelling, when it is a declared shortcode.
  * @returns {string} The message.
  * @throws {Error} On a reason outside the closed set — a resolver inventing one
  *   would otherwise report a link with no explanation at all.
  */
-export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, }: {
+export function linkFindingMessage({ reason, target, packages, anchor, type, stub, shortcode, declared, problems, }: {
     reason: string;
     target: string;
     packages?: Iterable<string> | undefined;
@@ -172,6 +175,7 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
     type?: string | undefined;
     stub?: string | undefined;
     shortcode?: string | undefined;
+    problems?: string[] | undefined;
     declared?: string | undefined;
 }): string;
 /**
@@ -188,9 +192,23 @@ export function isSamePage({ target, anchor }: ParsedWikilink): boolean;
  * Read an operational link target in its enclosing Address context.
  * @param {string} inner - Lexical link contents.
  * @param {object} context - Builder defaults and type vocabulary.
+ * @param {string} [literal] - Whole matched link, including trailing attributes.
  * @returns {object} Typed target and diagnostic source spelling.
  */
-export function readWikilink(inner: string, context: object): object;
+export function readWikilink(inner: string, context: object, literal?: string): object;
+/** Whether the actual referenced destination needs spoiler presentation.
+ * @param {object} destination - Resolved note metadata.
+ * @param {string} [anchor] - Referenced prose anchor.
+ * @returns {boolean} Whole-note or section audience.
+ */
+export function secretDestination(destination: object, anchor?: string): boolean;
+/** Apply destination-derived presentation without changing its address.
+ * @param {string} reference - Rendered reference Markdown.
+ * @param {object} parsed - Shared parsed wikilink.
+ * @param {object} destination - Resolved target metadata.
+ * @returns {string} Inline spoiler or visible reference.
+ */
+export function presentWikilink(reference: string, parsed: object, destination: object): string;
 /**
  * What a `[[…]]` **is**, before anything decides where it points.
  *
@@ -297,6 +315,25 @@ export type ParsedWikilink = {
      * is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
      */
     display: string | null;
+    /**
+     * - Trailing extension attributes.
+     */
+    attributes?: {
+        id: string;
+        classes: string[];
+        values: Record<string, string>;
+        problems: string[];
+        positions?: Record<string, {
+            key: {
+                start: number;
+                end: number;
+            };
+            value: {
+                start: number;
+                end: number;
+            };
+        }>;
+    } | undefined;
     /**
      * - Whether a `|` was present at all. A link
      * without one addresses nothing and is a finding — see