@rse/ase 1.0.7 → 2.0.0

package/plugin/meta/ase-common-task.md

@@ -5,7 +5,7 @@ Task Skill Common Steps
 <define name="task-react-id">
 
 1.  <if condition="
-        <instruction/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`
+        <instruction/> matches the regexp `^[a-zA-Z0-9#][a-zA-Z0-9#_-]*$`
     ">
     Set <ase-task-id><instruction/></ase-task-id> (set task
     id to instruction) and <instruction></instruction> (set
@@ -21,7 +21,7 @@ Task Skill Common Steps
 
 2.  <elseif condition="
         <instruction/> has the format `<id/>: <text/>` where
-        <id/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$` and
+        <id/> matches the regexp `^[a-zA-Z0-9#][a-zA-Z0-9#_-]*$` and
         <text/> is *empty*
     ">
     Set <instruction></instruction> (set instruction to empty)
@@ -64,6 +64,10 @@ Task Skill Common Steps
     <getopt-option-int-reuse-task/> is equal `true`
     *and* an `ase_task_save(id: '<ase-task-id/>', ...)` tool call
     exists earlier in the current session
+    *and* the `text` *argument* of the most recent such call carries
+    no `Effort:` frontmatter key without <hash/> (a bare size like
+    `Effort: M`, which the task store stamped or dropped on that save,
+    see the plan format)
 ">
     Set <text/> to the `text` *argument* of the most recent
     `ase_task_save(id: '<ase-task-id/>', ...)` tool call -- this is
@@ -76,6 +80,8 @@ Task Skill Common Steps
     Call the `ase_task_load(id: "<ase-task-id/>")` tool of the
     `ase` MCP server to load the current task plan content in its
     *authoring form* -- the `variant` argument defaults to `source`
+    -- with the payloads of all attachments *elided* to `[elided: <n/>
+    lines]` markers -- the `attachments` argument defaults to `elided`
     -- and set <text/> to the `text` output field of this
     `ase_task_load` tool call. Do not output anything related to
     this MCP tool call. Set <status>plan loaded</status>.
@@ -95,6 +101,73 @@ Only output the following <template/>:
 
 </define>
 
+<define name="task-ground-plan">
+
+Before deriving any plan content from the <instruction/>, *ground* the
+plan in the *current state* of the project, instead of deriving it from
+the <instruction/> alone. Do not output anything during this grounding.
+
+<if condition="<arg1/> is not empty">
+The *code basis* of the task is the separate working copy <arg1/>
+(e.g. a checkout of the branch of its `Source` key): resolve every
+project-relative file path below relative to <arg1/> and read the
+files *exclusively* from there, instead of from the current working
+copy.
+</if>
+
+1.  Call the `ase_artifact_list(kind: [ "spec", "code", "infr" ])` tool
+    of the `ase` MCP server *once* and read the returned `artifacts`
+    array of `{ kind, files }` objects to obtain the project-relative
+    file lists of the **Artifact Set**s `SPEC` (specification), `CODE`
+    (source code), and `INFR` (infrastructure, like build, deployment,
+    and operations configuration).
+
+2.  From these file lists, determine the files which the <instruction/>
+    *affects* or *depends on* -- the specification parts it touches or
+    which constrain it, the source code modules, interfaces, and symbols
+    it changes or uses, and the build, lint, test, packaging, and
+    deployment configuration it relies on -- and *read* them. Read only
+    the relevant files (or their relevant parts), not all files, but
+    always consider all three **Artifact Set**s.
+
+3.  Build a precise understanding of the *current state* and the
+    *conventions* of the project (structure, naming, coding style, build,
+    lint, and test procedures) from them.
+
+Then derive the plan from this grounding, where:
+
+-   the `##  SPECIFICATION (WHAT)` bullet-points are *consistent* with the
+    existing specification, and explicitly state any intended deviation
+    from it,
+-   the `##  DESIGN (HOW)` bullet-points name the *actual* files, modules,
+    interfaces, symbols, and configuration items to change, and place new
+    ones according to the existing structure and conventions, instead of
+    naming hypothetical ones,
+-   the `##  VERIFICATION (WHEN)` bullet-points (if any) refer to the
+    *actual* build, lint, and test procedures of the project, and
+-   if a `CHANGELOG.md` file exists in the project (or in any affected
+    sub-package), the `##  DESIGN (HOW)` section *MUST* include an
+    explicit `IMP` bullet-point describing the addition of a
+    corresponding new entry to that `CHANGELOG.md` file, aligned with
+    its existing style and conventions.
+
+</define>
+
+<define name="task-spec-format">
+
+The `SPEC` artifacts are in scope, so -- unless already done earlier in
+the current skill run -- use the `Read` tool to read the `SPEC` format
+contract, i.e., the files `meta/ase-format-specbook.md` (the SpecBook
+models and formats) and `meta/ase-format-spec.md` (the SpecBook project
+instantiation), each with its file path formed by joining
+<ase-plugin-root/> and the file name with exactly *one* `/` separator,
+as <ase-plugin-root/> may or may not carry a trailing `/`. You *MUST*
+then internalize and honor this `SPEC` format, plus the SpecBook schema
+configuration of the project, in all following work on `SPEC`
+artifacts. Do not output anything.
+
+</define>
+
 <define name="task-save-content">
 
 Update <timestamp-modified/> with the current time in ISO-style
@@ -110,8 +183,11 @@ refreshed <timestamp-modified/> into the frontmatter keys `Id:`,
 `Created:`, and `Modified:` of <task-content/>.
 
 Call the `ase_task_save(id: "<ase-task-id/>", text:
-"<task-content/>")` tool of the `ase` MCP server to save the task
-plan content in its *authoring form*. This `ase_task_save` MCP
+"<task-content/>", tag: true)` tool of the `ase` MCP server to save the task
+plan content in its *authoring form* -- the `tag: true` makes
+its output carry the `<task-plan-tag>` delimiter line, which
+lets a subsequent `ase-task-edit --int-reuse-task` reuse the
+just-saved plan instead of loading it again. This `ase_task_save` MCP
 tool call is the *only* permitted way to persist the task plan --
 you *MUST* *NEVER* write the plan file via `Write`/`Edit` or by
 executing a shell command. Do not output anything
@@ -163,6 +239,9 @@ Set <args>--int-reuse-task</args>.
 <if condition="<getopt-option-next/> is not equal `none`">
     Set <args><args/> --next <getopt-option-next/></args>
 </if>
+<if condition="<arg3/> is given and not empty">
+    Set <args><args/> <arg3/></args>
+</if>
 Only output the following <template/> and then call the tool
 `Skill(skill: "ase:<arg1/>", args: "<args/>")` to invoke the
 `ase:<arg1/>` skill to continue with the updated plan. Immediately

package/plugin/meta/ase-constitution.md

@@ -50,5 +50,3 @@ which boosts you to an expert-level Software Engineering AI agent.
 - When generating temporary helper programs or scratch test files, prefer the *target project's primary
   programming language* and *clean them up* once they are no longer needed.
 
-@./ase-persona.md
-

package/plugin/meta/ase-format-specbook.md

@@ -123,7 +123,7 @@ type SchemaDiagram = {
     config?:           Partial<GradiaConfig>
 }
 type SchemaFormat = {
-    type?:             "auto" | "complex" | "concise"
+    type?:             "auto" | "complex" | "compact" | "concise"
     maxTableColumns?:  number
     maxCellHeight?:    number
     withUnusedProps?:  boolean
@@ -151,6 +151,9 @@ type SchemaGradiaConfig = Partial<{
     "color-node-ghost-name":     string
     "color-node-ghost-box":      string
     "color-node-ghost-border":   string
+    "color-node-self-name":      string
+    "color-node-self-box":       string
+    "color-node-self-border":    string
     "color-group-name":          string
     "color-group-box":           string
     "color-group-border":        string
@@ -251,11 +254,13 @@ type SchemaGradiaConfig = Partial<{
     livelocks are ruled out
 
 -   `SchemaObject.diagram?: SchemaDiagram`:
-    diagram generated for every object of this kind,
+    diagram generated for every object of this kind (left out when the
+    configuration is emitted compressed by level 2 or higher),
     BECAUSE relations buried in references are graspable only when drawn
 
 -   `SchemaObject.format?: SchemaFormat`:
-    HTML/PDF rendering format of the objects of this kind,
+    HTML/PDF rendering format of the objects of this kind (left out when
+    the configuration is emitted compressed by level 2 or higher),
     BECAUSE rich objects need sections, uniform ones read as tables
 
 -   `SchemaObject.props?: SchemaProperty[]`:
@@ -318,7 +323,8 @@ type SchemaGradiaConfig = Partial<{
 -   `SchemaDiagram.center?: string | SchemaDiagramCenter`:
     object a `hub` diagram is projected onto (default: `self`), or a
     synthetic center node, labeled from a referenced `source` object (or
-    one of its properties, via `property`) or a literal `label`, typed
+    one of its properties, via `property`, falling back onto the `label`
+    or the object name while absent) or a literal `label`, typed
     (under `qualified`) by `kind`, and linked to the `source` object,
     BECAUSE the focus of a hub is not always a specification object --
     the solution itself, e.g., sits in the middle of a context diagram
@@ -417,15 +423,16 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE the node name alone rarely makes the nodes comparable
 
 -   `SchemaDiagram.config?: SchemaGradiaConfig`:
-    arbitrary Gradia rendering options (e.g. `grid-columns-max: 5`),
+    arbitrary Gradia rendering options (e.g. `grid-columns-max: 2`),
     BECAUSE layout tuning is cosmetics, not a schema concern
 
 -   `SchemaFormat`:
     HTML/PDF rendering of the objects of an object kind among their siblings,
     BECAUSE one uniform rendering fits neither rich nor numerous objects
 
--   `SchemaFormat.type?: "auto" | "complex" | "concise"`:
-    rendering: `complex` (sections), `concise` (tables), or `auto`,
+-   `SchemaFormat.type?: "auto" | "complex" | "compact" | "concise"`:
+    rendering: `complex` (sections), `concise` (tables), `compact`
+    (tables of section-like cells), or `auto`,
     BECAUSE sections bury small objects, tables truncate rich ones
 
 -   `SchemaFormat.maxTableColumns?: number`:
@@ -498,7 +505,8 @@ type SchemaGradiaConfig = Partial<{
     BECAUSE an embedded font renders alike where it is not installed
 
 -   `SchemaGradiaConfig."color-node-*": string`:
-    colors of the node boxes in their regular, primary, and ghost role,
+    colors of the node boxes in their regular, primary, ghost, and self
+    role,
     BECAUSE the role of a node has to be readable at a glance
 
 -   `SchemaGradiaConfig."color-group-*", "color-edge-*": string`:
@@ -557,13 +565,16 @@ that kind. Its `type` selects the diagram shape (`graph`, `hub`, or
 `grid`), `nodes` and `edges` select the participating objects through
 comma-separated `[[xxx]]` reference patterns (`nodes` defaults to the
 object itself plus all objects below it), and `center` names the object
-a `hub` is projected onto (default: `self`).
+a `hub` is projected onto (default: `self`). An edge object of the
+center targeting the center itself (a self-reference) places the center
+a second time among its outputs, rendered as a dashed "self" node.
 
 Instead of naming an existing object, `center` can also declare a
 *synthetic* center node, which represents something no specification
 object models -- like the solution itself in the middle of a context
 diagram. Such a center is labeled from a referenced `source` object (or
-one of its properties, via `property`) or a literal `label`, and links
+one of its properties, via `property`, falling back onto the `label` or
+the object name while the property is absent) or a literal `label`, and links
 to the `source` object. As the nodes carry no `[[xxx]]` reference to a
 synthetic center, `centerEdges` synthesizes the edges from a direction
 `property` of the node objects: its `inbound` value maps onto a
@@ -577,7 +588,15 @@ node only, `qualified` labels every node with its object kind,
 `properties` lists the property names whose values are attached to the
 nodes as key/value annotations (with every `[[xxx]]` reference stripped
 to its target object name), and `config` passes arbitrary Gradia
-rendering options (e.g. `grid-columns-max: 5`) through to the diagram.
+rendering options (e.g. `grid-columns-max: 2`) through to the diagram.
+As the Gradia defaults are dimensioned for a stand-alone canvas,
+SpecBook presets a compact geometry for every diagram, which `config`
+overrides: `size-canvas-margin: 8`, `size-node-height-scale: 2`,
+`hub-node-gap: 10`, `hub-node-count-max: 6` (a `hub` column of more
+nodes wraps into two staggered sub-columns), `grid-gap-horizontal: 24`,
+`grid-gap-vertical: 12`, and `grid-columns-min: 4` (the square
+derivation of the column count otherwise leaves a third of the document
+width unused).
 
 `ordered` replaces the layered layout of a `graph` by the document
 order of the objects: the top-level nodes stack top-down in that order
@@ -633,15 +652,20 @@ how the HTML/PDF export renders the objects of that kind among their
 siblings, so that the sibling kinds below one parent can render
 differently (e.g. one kind as a table, another as sections). Its `type`
 selects the rendering: `complex` (nested sections), `concise` (one
-compact table of all sibling objects of the kind), or the default
-`auto`, which collapses only the deepest level into tables.
+compact table of all sibling objects of the kind), `compact` (one
+table of the name and a single cell per object, which renders the
+object like `complex`, but without its heading: diagram, properties as
+key/value lines, and description, for a kind whose many properties a
+table row cannot hold), or the default `auto`, which collapses only the
+deepest level into tables.
 
 Inside a `concise` table, unconfigured child kinds implicitly stay
 `concise` and render as sub-tables inside the description cells, while
 an explicitly configured `type` is always honored, even a `complex`
 rendering pressed into a cell. `maxTableColumns` (default: `4`) bounds
 the columns of the compact table of the kind (a wider group chunks
-its properties into embedded per-object tables), `maxCellHeight`
+its properties into embedded per-object tables, while a `compact`
+one ignores it), `maxCellHeight`
 (default: `40`) is the percentage a table cell of the kind may exceed
 the height of every other non-empty cell of its row before the HTML
 export folds its remaining text away, and `withUnusedProps`
@@ -686,6 +710,7 @@ type SpecObject = {
 type SpecDescription = {
     description:       string
     rationale?:        string
+    elaboration?:      string
     embedding?:        string[]
 }
 type SpecProperty = {
@@ -760,7 +785,7 @@ type SpecProperty = {
     BECAUSE a specification is a tree, not a flat list of statements
 
 -   `SpecDescription`:
-    description of an object: statement, rationale, and images,
+    description of an object: statement, rationale, elaboration, and images,
     BECAUSE the WHAT and the WHY are stored apart to be rendered apart
 
 -   `SpecDescription.description: string`:
@@ -769,11 +794,18 @@ type SpecProperty = {
 
 -   `SpecDescription.rationale?: string`:
     rationale text behind the `, BECAUSE ` split (the WHY),
+    up to the end of its paragraph,
     BECAUSE a statement without its WHY cannot be judged or revised
 
+-   `SpecDescription.elaboration?: string`:
+    blocks following the paragraph of the rationale (e.g. images or diagrams),
+    BECAUSE further content must not end up inside the WHY
+
 -   `SpecDescription.embedding?: string[]`:
-    image files embedded via `![xxx](yyy)`, inlined at parse time,
-    one entry per file in markup order (empty for an unreadable file),
+    image, diagram source, and source code files embedded via `![xxx](yyy)`,
+    inlined at parse time, one entry per file in markup order (those of
+    the statement first, those of the elaboration second, and empty for
+    an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
 -   `SpecProperty`:
@@ -789,7 +821,8 @@ type SpecProperty = {
     BECAUSE constraints and references are checked against this text
 
 -   `SpecProperty.embedding?: string[]`:
-    image files embedded in the value, inlined at parse time,
+    image, diagram source, and source code files embedded in the value,
+    inlined at parse time,
     one entry per file in markup order (empty for an unreadable file),
     BECAUSE the exports have to stand alone, without the image files
 
@@ -976,10 +1009,15 @@ paragraphs, blockquotes, ordered lists (e.g. scenario steps or test
 case procedures), and fenced code blocks. A fenced code block of
 language `gradia` is skipped, as it is the derived diagram which
 **SpecBook** itself emits into exported Markdown and which must not
-become authored content on a re-parse. In the Concise Format, the
-description is formed by the non-property segments of the item, so a
-description carrying a `;` cannot be a segment either and forces its
-object into the Complex Format.
+become authored content on a re-parse. A fenced code block of language
+`mermaid` (alias `mmd`) or `d2` is a [Mermaid](https://mermaid.js.org/)
+or [D2](https://d2lang.com/) diagram, which the HTML/PDF export renders
+as a diagram instead of as code (see "Diagram Embeddings" below). A
+fenced code block of any other known language is a syntax-highlighted
+code listing (see "Code Listings" below). In
+the Concise Format, the description is formed by the non-property
+segments of the item, so a description carrying a `;` cannot be a
+segment either and forces its object into the Complex Format.
 
 A description is split into its *statement* and *rationale* at the first
 `, BECAUSE ` (or `, **BECAUSE** `) occurrence:
@@ -989,10 +1027,25 @@ The event is created and configured but not visible to attendees,
 BECAUSE an event needs a private setup phase.
 ```
 
+The rationale ends with its paragraph: all blocks following it (further
+paragraphs, embedded images, and diagrams) form the *elaboration*, which
+is rendered below the statement and its rationale, so the description
+of a Complex Format object can state its WHAT and WHY first and
+illustrate them afterwards:
+
+````
+The event is created and configured but not visible to attendees,
+BECAUSE an event needs a private setup phase.
+
+![Event Lifecycle](event-lifecycle.mmd)
+````
+
 ### Wiki-Style References
 
 A `[[<reference/>]]` anywhere in a name, property value, description, or
-rationale is a Wiki-style reference to another object, which is checked
+rationale (except inside a fenced code block, whose code stays verbatim,
+so e.g. a shell test `[[ -f x ]]` is no reference) is a Wiki-style
+reference to another object, which is checked
 for unique resolvability and rendered as a hyperlink in the HTML/PDF
 exports. A reference is a `.`-separated path of segments, where each
 segment matches a single object as:
@@ -1026,8 +1079,25 @@ constrain reference-valued properties (e.g. `[[PERSONA:*]]` or
 
 A Markdown image `![<alt/>](<file/>)` inside a description or property
 value embeds a local image file, resolved relative to the artifact file:
-SVG files are inlined as-is; PNG/JPEG files are embedded as base64
-`data:` URLs. URLs and other file types are left untouched.
+SVG files are inlined as-is; PNG/JPEG/WebP files are embedded as base64
+`data:` URLs. URLs and other file types are left untouched. The
+HTML/PDF export optimizes the embedded images on its own (downscaled
+and re-encoded PNG/JPEG/WebP, minified SVG), so the files can stay in their
+original resolution. Like a diagram, an embedded image (except the logo
+of the title page) folds, maximizes, and is omitted (`-O diagram:image`,
+or by nesting level) in the HTML/PDF export, while the AST exports keep
+it.
+
+A page of a PDF document is embedded like an image --
+`![<alt/>](<file/>.pdf)` for the first page, or
+`![<alt/>](<file/>.pdf#page=<n/>)` for the 1-based page number `<n/>` --
+where the document is inlined at parse time. The exports convert the
+page through `pdfjs-dist` into a vector SVG with its texts as glyph
+outlines and then treat it exactly like an embedded SVG image, while a
+page failing to render (e.g. an absent page number) is omitted with a
+notice. A presentation (e.g. PowerPoint), a spreadsheet (e.g. Excel), or
+any other office document is embedded through its PDF export, which
+carries its exact rendering and fonts.
 
 A reference carrying the `{theme}` placeholder -- e.g.
 `![Logo](logo-{theme}.svg)` -- is a *theme-aware* embedding: it expands
@@ -1036,3 +1106,116 @@ both of which are embedded, as two consecutive entries in this order. The
 HTML export shows just the variant matching the color theme currently
 active in the document, while the PDF export (like print in general)
 always uses the `light` variant.
+
+An image without a dark variant is treated on the dark theme of the HTML
+export as its `dark` fragment parameter says (see "Fragment Parameters"
+below), while print always keeps it as it is. An image defaults to
+`dark=auto`, which inverts it (with its hues rotated back) if it most
+likely draws dark lines onto a transparent or light canvas: an SVG if it
+neither adapts itself (via `light-dark()` colors, `prefers-color-scheme`
+rules, or a `color-scheme` declaration, which follows the color theme of
+the document anyway), nor embeds a raster image, nor paints a background
+which is not light, and a raster image (PNG/JPEG/WebP) if at least 60%
+of its pixels are transparent or near-white and the others are dark on
+average and of a few colors only (unlike a photo or a colorful
+screenshot). As the detection cannot tell a logo or illustration with
+brand colors from a line drawing, `#dark=none` keeps such an image as it
+is, while `#dark=invert` forces the inversion (e.g.
+`![Overview](overview.svg#dark=invert)`). A
+[draw.io](https://www.drawio.com/) diagram is best embedded as its
+editable SVG (`.drawio.svg`, which draw.io keeps current on every save)
+with its "Adaptive Colors" page setting on "Automatic", as it then
+adapts all its colors itself. A theme-aware embedding ignores the
+fragment, as its `dark` variant already serves the dark theme.
+
+The reference-style image `![<alt/>][<label/>]` embeds the image of its
+definition `[<label/>]: data:image/<type/>;base64,<data/>` (SVG, PNG,
+JPEG, or WebP, where a `;dark=invert` or `;dark=none` parameter behind
+the type carries the treatment on the dark theme, which the export
+always resolves for an SVG) in the same file, the only supported link
+definition.
+This is the form the normalized Markdown export emits for every embedded
+image (a theme-aware one by its `light` variant), with the definitions
+at the end of the document, so it stands alone without the image files.
+Author the inline form; the reference-style one is for re-parsing only.
+
+### Diagram Embeddings
+
+A [Mermaid](https://mermaid.js.org/) or [D2](https://d2lang.com/)
+diagram is either written inline into a description as a fenced code
+block of language `mermaid` (alias `mmd`) or `d2`, or kept in a file of
+its own and embedded like an image -- `![<alt/>](<file/>.mmd)`,
+`![<alt/>](<file/>.mermaid)`, or `![<alt/>](<file/>.d2)` -- inside a
+description or property value, where its source is inlined at parse time.
+The HTML/PDF export renders every such diagram (Mermaid through
+`beautiful-mermaid`, D2 through `@d2lang/d2`, laid out by its TALA
+engine unless the diagram configures another `layout-engine`) in the
+theme colors of the document, once per color theme, like a theme-aware
+image. It folds,
+maximizes, and is omitted (`-O diagram:code`, for diagrams as code, or
+by nesting level) like a derived Gradia diagram. A diagram failing to render
+is omitted with a notice. The normalized Markdown and the AST exports
+carry the source of a fenced diagram as part of the description, and an
+embedded diagram file as its rendered SVG (the `light` variant).
+
+### Code Listings
+
+A code snippet is either written inline into a description as a fenced
+code block of a known language (any language id or alias of
+[Shiki](https://shiki.style/), like `ts`, `java`, `css`, or `html`), or
+kept in a source code file of its own and embedded like an image --
+`![<alt/>](<file/>.<ext/>)`, where `<ext/>` is such a language id or
+alias (e.g. `.ts`, `.java`, `.css`, `.html`) -- inside a description or
+property value, where its source is inlined at parse time. A fenced code
+block of no or an unknown language stays plain preformatted text.
+
+The HTML/PDF export renders every such snippet as a *code listing* in
+DejaVu Sans Mono, with line numbers and with its keywords, operators,
+and punctuation in the accent color and bold, its literals in the signal
+color, and its comments in the dim color and italic. A code listing
+folds, maximizes, and is omitted (`-O diagram:listing`, or by nesting
+level) like a diagram.
+
+A fenced code listing takes whitespace-separated parameters behind its
+language, and an embedded one takes them as its fragment (see "Fragment
+Parameters" below):
+
+-   `start=<n/>` (fenced only): the number of the first line (default `1`).
+-   `lines=<a/>-<b/>` or `lines=<a/>` (embedded only): the excerpt of the
+    1-based lines `<a/>` to `<b/>` (or line `<a/>` alone), numbered from
+    `<a/>`, where an empty range is reported as an error.
+-   `mark=<a/>[-<b/>][,...]`: the lines or line ranges to mark (in the
+    shown line numbers) on a very light signal background.
+
+````
+```ts start=10 mark=12-13
+const greeter = new Greeter("World")
+```
+
+![Greeter Class](greeter.ts#lines=5-20&mark=8,12-14)
+````
+
+The AST exports carry an embedded source code file as its
+`data:text/x-code;lang=<lang/>;start=<n/>[;mark=<hunks/>];base64,<data/>`
+URL, while the normalized Markdown export turns one of a description into
+a fenced code block (with its `start` and `mark` parameters) at the end
+of the elaboration, and keeps one of a property value as a
+reference-style image definition of that URL.
+
+#### Fragment Parameters
+
+The fragment of an embedding reference is a list of `<key/>=<value/>`
+parameters joined by `&`, in any order and each at most once, with the
+values optionally URI-encoded (e.g. `%20` for a space): `page`
+(documents), `dark` (documents and images), and `lines` and `mark`
+(source code files, see "Code Listings" above). A fragment carrying any
+other key or an invalid value is reported as an error. The `dark`
+parameter selects the treatment on the dark theme of the HTML export,
+while print always shows the original: `dark=invert` inverts the
+embedding with its hues rotated back, `dark=none` shows it as it is, and
+`dark=auto` (the default) decides by the content of the image or the
+rendered document page (inverting a light canvas with dark ink, but
+neither a dark one nor one carrying a photo), as an image and a document
+page can be anything (line drawings, photos, logos); e.g.
+`![<alt/>](<file/>.pdf#page=3&dark=none)` keeps a page which the
+detection would invert, but whose colors have to stay.