@peaceroad/markdown-it-figure-with-p-caption 0.19.0 → 0.20.0

package/docs/numbering.md

@@ -0,0 +1,215 @@
+# Automatic numbering and integration API
+
+This document describes automatic numbering, chapter and appendix scopes,
+frontmatter and render overrides, and the public numbering integration API.
+For general behavior and options, see the [behavior reference](reference.md).
+For installation and the minimum setup, start with the
+[project README](../README.md).
+
+## Contents
+
+- [Automatic numbering](#automatic-numbering)
+- [Chapter and appendix scopes](#chapter-and-appendix-scopes)
+- [Caption-numbering integration API](#caption-numbering-integration-api)
+
+## Automatic numbering
+
+Automatic numbering is disabled by default.
+
+- `autoLabelNumberSets`: strict caption-mark allowlist. Supported entries are `img`, `table`, `code` / `pre-code`, `samp` / `pre-samp`, and `video`; aliases are deduplicated to their canonical marks.
+- `autoLabelNumber`: shorthand for turning numbering on for both images and tables without passing the array yourself. Provide `autoLabelNumberSets` explicitly (e.g., `['img']`) when you need finer control—the explicit array always wins.
+- Recognized chapter/appendix scopes are applied automatically whenever at least one mark is numbered. By default, parsed `env.frontmatter.title` values and top-level H1 headings are sources, repeated semantic scopes continue their prior counters, and `.` joins the scope prefix to the local number.
+- `autoLabelNumberPolicy`: customize the automatic scope, separator, and repeated-scope behavior without enabling any media type by itself. Use `scope: 'document'` for document-wide decimal counters regardless of recognized headings/frontmatter.
+- Do not pass p-captions' lower-level `setFigureNumber` option to this plugin. Figure numbering is owned by `autoLabelNumber` / `autoLabelNumberSets`; `setFigureNumber` is rejected during the initial setup to prevent two numbering systems from mutating the same caption.
+- An explicit `[]` disables numbering even when `autoLabelNumber` is true. Explicit `undefined`, `null`, non-arrays, unsupported marks, and invalid entries throw during initial setup instead of being silently ignored.
+- Numbering enablement follows `captionDecision.mark`, not the wrapper class. A known video iframe with a `Figure.` caption requires `img`; the same iframe with `Video.` requires `video`. An unknown iframe with an explicit `Video.` caption also uses the video counter, while its wrapper remains `f-iframe`.
+- Counters start at `1` and use semantic series independent of wrapper/label classes: `img` uses `figure`, `pre-code` uses `listing`, `video` uses `video`, and `table` uses `table`. A `pre-samp` caption uses the figure series when its source label is also an image label (`図`), the listing series when it is also a code label (`リスト`), and otherwise its own samp series (`端末`, `Terminal`, etc.). The overlap check reuses p-captions' active language catalog rather than hardcoded label text.
+- A disabled mark never advances a shared series. Therefore image/`図` samp captions or code/`リスト` samp captions share source-order numbering only when both canonical marks are enabled.
+- The counter only advances when a real caption exists (paragraph, auto-detected alt/title, or fallback text). Figures emitted solely because of `imageOnlyParagraphWithoutCaption` / `oneImageWithoutCaption` stay unnumbered.
+- Manual numbers inside the caption text (e.g., `Figure 5.`) always win. The plugin reads the exact `captionDecision.number` supplied by `p7d-markdown-it-p-captions` and updates the selected semantic series so the next automatic number becomes `6`, even when the next caption has a different mark sharing that series. Explicit compound/alphanumeric numbers (e.g., `Figure A.` or `Figure A.5.`) are preserved without appending an automatic number and do not seed an unscoped decimal counter. This applies to captions sourced from paragraphs, auto detection, and fallback captions.
+- With `removeUnnumberedLabel: true`, the enabled-set filter uses the canonical decision mark, not its semantic counter key. For example a samp block labeled `図` still needs `samp` / `pre-samp` in `removeUnnumberedLabelExceptMarks`, not `img`.
+- Number generation and label-token construction now share p-captions' policy/runtime engine. The source-only `captionDecision` remains unchanged when a number is generated, and callback/configuration failures occur before this plugin commits caption-token or counter changes.
+- Generated numbers must remain inside p-captions' caption-number grammar. In particular, advancing `999999` to a seven-digit segment throws a `RangeError` before the affected caption is mutated.
+
+### Chapter and appendix scopes
+
+The default policy derives a display prefix and an independent counter sequence
+from top-level H1 headings and parsed per-render frontmatter metadata:
+
+```js
+const md = mdit({ html: true }).use(mditFigureWithPCaption, {
+  autoLabelNumber: true,
+})
+```
+
+```md {test id="numbering-default-scope" setup="numbered"}
+# Chapter 1: Introduction
+
+Figure. Architecture
+
+![Architecture](architecture.png)
+```
+
+```html {test id="numbering-default-scope"}
+<h1>Chapter 1: Introduction</h1>
+<figure class="f-img">
+<figcaption><span class="f-img-label">Figure 1.1<span class="f-img-label-joint">.</span></span> Architecture</figcaption>
+<img src="architecture.png" alt="Architecture">
+</figure>
+```
+
+Customize the policy when the document uses another heading level, needs one
+source only, resets repeated scope occurrences, or uses `-`:
+
+```js
+const md = mdit({ html: true }).use(mditFigureWithPCaption, {
+  autoLabelNumber: true,
+  autoLabelNumberPolicy: {
+    separator: '-',
+    scope: {
+      sources: ['heading'],
+      headingLevels: [2],
+      repeatScope: 'reset',
+    },
+  },
+})
+```
+
+Within a scope object, `sources` defaults to `['frontmatter', 'heading']`,
+`headingLevels` to `[1]`, and `repeatScope` to `'continue'`. `scope: 'auto'`
+selects those defaults. An explicit `sources: []` disables inferred sources
+while still allowing a fixed render-level scope.
+
+Recognized leading scope forms are `Chapter N`, `第N章`, `N章`, `Appendix N`, `Appendix A`, and `付録` / `付属` / `附属` followed by a digit or one uppercase ASCII letter. English keywords are case-insensitive. The marker must end at the same spaced/compact caption boundary used by p-captions, so prose such as `Chapter 1st`, `Appendix API`, or `第1章立て` is not mistaken for a scope. Formatting after a valid boundary is allowed (`# Chapter 1: *Introduction*`), but formatting the marker itself (`# **Chapter 1**`) and ambiguous inline-token continuations fail closed.
+
+- Only configured top-level heading levels update scope. Headings inside blockquotes/lists do not become scope sources in this release, although figures inside those containers inherit the current top-level scope.
+- Captions before the first recognized scope use the ordinary unscoped decimal sequence.
+- With `repeatScope: 'continue'`, a repeated semantic scope resumes its prior per-mark counter. With `repeatScope: 'reset'`, every scope occurrence gets a new render-local counter partition even when its displayed prefix is identical.
+- In scoped mode, an explicit number seeds the counter only when it uses the active prefix and separator (for example, `Figure 2.5.` under `Chapter 2` with the default separator). Other explicit numbers are preserved as source text but do not seed that sequence.
+- To retain document-wide numbering for every render, set `autoLabelNumberPolicy: { scope: 'document' }`. Explicit `autoLabelNumberPolicy: null` remains an equivalent compatibility opt-out. Per-render frontmatter/env overrides described below can still select `document` when automatic scope is configured.
+
+The canonical frontmatter input is parsed metadata supplied per render as `env.frontmatter.title`:
+
+```js
+md.render(source, { frontmatter: { title: 'Appendix A: Data' } })
+```
+
+This plugin does not register a frontmatter block rule and does not parse YAML. If the host already produces a `front_matter` token, provide `resolveFrontmatterTitle(raw, state)` to adapt its raw string. Resolver errors and non-string results fail closed to the unscoped sequence. `markdown-it-front-matter` is used only as a development/integration-test adapter here; adding that detector alone does not parse a YAML `title`.
+
+```js
+autoLabelNumberPolicy: {
+  scope: {
+    resolveFrontmatterTitle(raw, state) {
+      const match = raw.match(/^title:\s*(.+)$/m)
+      return match ? match[1] : null
+    },
+  },
+}
+```
+
+Parsed frontmatter may override the configured scope mode and separator for one document through the nested `figure-caption-numbering` object:
+
+```yaml
+---
+title: Chapter 1. A title
+figure-caption-numbering:
+  scope: auto
+  separator: "."
+---
+```
+
+The equivalent render input is:
+
+```js
+md.render(source, {
+  frontmatter: {
+    title: 'Chapter 1. A title',
+    'figure-caption-numbering': {
+      scope: 'auto',
+      separator: '.',
+    },
+  },
+})
+```
+
+The equivalent flattened form is also accepted when a frontmatter pipeline exposes dotted keys:
+
+```yaml
+---
+title: Chapter 1. A title
+figure-caption-numbering.scope: auto
+figure-caption-numbering.separator: "."
+---
+```
+
+Nested and dotted properties may be combined when they configure different fields, but defining the same logical field twice throws instead of choosing an ambiguous winner. Abbreviated aliases are intentionally not recognized.
+
+`scope: 'auto'` uses the heading/frontmatter sources enabled by
+`autoLabelNumberPolicy.scope`; its default sources are parsed frontmatter
+titles and top-level H1 headings. It does not re-enable a source removed by an
+explicit `sources` array. `scope: 'document'` fixes the render to the unscoped
+per-series counters, so a recognized `Chapter 1` still produces `Figure 1`,
+`Figure 2`, and so on. `separator` accepts only `.` or `-` and overrides the
+setup-time separator for that render. The default is `.`, so `Chapter 1`
+produces `Figure 1.1`; select `-` for `Figure 1-1`.
+
+Unknown nested properties, invalid values, and duplicate nested/dotted definitions throw before caption mutation.
+
+A host may override parsed frontmatter through `env.figureCaptionNumbering`. Its `scope` may be `'auto'`, `'document'`, or a validated fixed scope object. A render-level `separator` takes precedence over parsed frontmatter, which in turn takes precedence over `autoLabelNumberPolicy.separator`:
+
+```js
+md.render(source, {
+  figureCaptionNumbering: {
+    separator: '.',
+    scope: {
+      scopeKey: 'chapter:7',
+      sequenceKey: 'edition-2:chapter:7',
+      displayPrefix: '7',
+    },
+  },
+})
+```
+
+When `sequenceKey` is omitted from a fixed scope it defaults to `scopeKey`; specify it when semantic identity and counter partition must differ. Invalid explicit overrides throw before caption mutation rather than silently falling back to the unscoped sequence.
+
+### Caption-numbering integration API
+
+Source editors and other markdown-it integrations can reuse the figure-specific numbering semantics without importing the renderer walker:
+
+```js
+import {
+  createFigureCaptionCounterKeyResolver,
+  createFigureCaptionNumberCodec,
+  createFigureCaptionScopeTimeline,
+  normalizeFigureCaptionNumberingPolicy,
+} from '@peaceroad/markdown-it-figure-with-p-caption/caption-numbering.js'
+```
+
+- `normalizeFigureCaptionNumberingPolicy(value)` applies the same validation and defaults as `autoLabelNumberPolicy`. `undefined` or an object with no scope fields uses the automatic defaults; `scope: 'document'` creates an unscoped policy. Only explicit `null` returns `null`; otherwise the helper returns an opaque frozen policy that must be passed to the timeline API.
+- `createFigureCaptionScopeTimeline(state, policy)` reads a markdown-it `StateCore` after inline parsing and returns the initial numbering context plus frozen, source-ordered top-level heading boundaries. It applies the same parsed-frontmatter, render override, heading level, marker boundary, separator, and repeat-scope rules as the renderer. It never mutates `state`, its tokens, or inline children. A recognized heading without a usable `token.map` sets `hasUnmappableBoundaries` so a source editor can fail closed rather than guess an edit range.
+- `createFigureCaptionCounterKeyResolver({ languages })` returns a frozen resolver from a p-captions `captionDecision` to the same semantic `figure` / `listing` / `samp` / `video` / `table` series used by this plugin. The language catalog is normalized once when the resolver is created.
+- `createFigureCaptionNumberCodec()` returns a frozen stateless codec. `parseExplicit(number, context)` returns the compatible positive decimal counter value or `null`; `format(sequence, context)` generates the scoped or unscoped number and enforces p-captions' number grammar. Contexts are branded frozen values returned by the timeline API, so arbitrary look-alike objects are rejected.
+
+Create the timeline inside a core rule so the real `StateCore`, including `env` and inline children, stays available:
+
+```js
+const policy = normalizeFigureCaptionNumberingPolicy({
+  separator: '.',
+  scope: {
+    sources: ['frontmatter', 'heading'],
+    headingLevels: [1],
+    repeatScope: 'continue',
+  },
+})
+
+md.core.ruler.after('inline', 'collect_figure_caption_scopes', (state) => {
+  const timeline = createFigureCaptionScopeTimeline(state, policy)
+  // Collect source edits here or store the immutable timeline in render-local state.
+  state.env.figureCaptionScopeTimeline = timeline
+})
+```
+
+This subpath intentionally does not expose figure-candidate detection, wrapping, or token mutation. `p7d-markdown-it-p-captions` still owns caption grammar and `captionDecision`; consumers own source selection and editing.
+
+For complete rendered samples and configuration variations, see
+[Complete conversion and option examples](examples.md).

package/docs/reference.md

@@ -0,0 +1,148 @@
+# Behavior and options reference
+
+This document contains the detailed behavior and option reference for
+`@peaceroad/markdown-it-figure-with-p-caption`. For installation, quick-start
+guidance, recommended options, and representative conversions, start with the
+[project README](../README.md).
+
+## Contents
+
+- [Behavior](#behavior)
+- [Behavior customization](#behavior-customization)
+- [Basic usage](#basic-usage)
+- [Recommended options](#recommended-options)
+- [Automatic numbering and integration API](numbering.md)
+- [Complete conversion and option examples](examples.md)
+
+## Behavior
+
+Calling `.use(mditFigureWithPCaption)` more than once on the same markdown-it instance is intentionally a no-op after the first successful call, before later options are validated. Initial setup validates and registers the rule before setting its installed sentinel, so a failed first setup can be corrected on the same markdown-it instance. Create a separate instance when you need a different successful option set.
+
+### Image
+
+- Pure image paragraphs (`![...](...)`) become `<figure class="f-img">` blocks as soon as a caption paragraph (previous or next) or an auto-detected caption exists.
+- Auto detection runs per image paragraph when `autoCaptionDetection` is `true` (default). The priority is:
+    1. Caption paragraphs immediately before or after the image (standard syntax).
+    2. Image `alt` text that `p7d-markdown-it-p-captions` recognizes as an image caption start (`Figure. `, `Figure 1. `, `図　`, `図1　`, etc.).
+    3. Image `title` attribute that matches the same labels.
+    4. Optional fallbacks (`autoAltCaption`, `autoTitleCaption`) that inject the label when the alt/title lacks one.
+        - `autoAltCaption`: `false`/`null` (off), `true`, or a string label. `true` uses locale-aware generated-label defaults from `p7d-markdown-it-p-captions`, so the label text and punctuation stay aligned with the upstream caption language data. A string is treated as a label stem that must be recognized by `p7d-markdown-it-p-captions`; setup throws if it cannot be parsed as an image caption label. Other value types are rejected. This plugin appends the default joint/space unless the string already ends with a recognized joint such as `.` / `。` / `:` / `　`. Empty alt text does not generate a fallback caption.
+        - `autoTitleCaption`: same behavior but sourced from the image `title`. It stays off by default so other plugins can keep using the `title` attribute for metadata.
+- Set `autoCaptionDetection: false` to disable the auto-caption workflow entirely.
+- Multi-image paragraphs are still wrapped as one figure when `multipleImages: true` (default). Layout-specific classes help with styling:
+  - `f-img-horizontal` when images sit on the same line (space-delimited).
+  - `f-img-vertical` when separated only by soft breaks.
+  - `f-img-multiple` for mixed layouts.
+- Automatic detection inspects only the first image in the paragraph. If it yields a caption, the entire figure reuses that caption while later images keep their own `alt`/`title`.
+- Paragraphs that contain only images also convert when they appear inside loose lists (leave blank lines between items), blockquotes, or description lists.
+- Caption detection intentionally skips paragraphs that are the first block inside a list item (`list_item_open` immediately before the paragraph). In practice, `- Figure. ...` followed by an image in the same item is treated as plain text unless you insert another block first.
+- A media candidate that ultimately cannot be wrapped (for example, an image paragraph with trailing prose) no longer causes an adjacent caption paragraph to be decorated as a side effect. This is an intentional correctness fix from 0.19.0; valid figures retain the existing output.
+
+### Table
+
+- Markdown tables (including those produced by `markdown-it-multimd-table` or similar) convert into `<figure class="f-table">` blocks.
+- Caption paragraphs immediately before/after the table become `<figcaption>` element ahead of the `<table>`.
+
+### Code block
+
+- Captions labeled `Code. `, `Terminal. `, etc. wrap the fence in `<figure class="f-pre-code">` / `<figure class="f-pre-samp">`.
+- If `roleDocExample: true`, these figures add `role="doc-example"`.
+
+### Blockquote
+
+- Captioned blockquotes (e.g., `Source. A paragraph.` written immediately before or after `> ...`) become `<figure class="f-blockquote">` while keeping the original blockquote intact.
+
+### Video & Audio
+
+- Block HTML `<video>` and `<audio>` tags are detected as media figures (`<figure class="f-video">` and `<figure class="f-audio">`). A single-line tag parsed by markdown-it as inline HTML is not promoted to a block figure.
+- A caption paragraph labeled `Video. ` / `Audio. ` (or any registered label) is promoted to `<figcaption>` before/after the media so controls remain unobstructed.
+
+### Embedded content by iframe
+
+- HTML blocks containing `<iframe>` elements become `<figure class="f-video">` when they point to known video hosts (YouTube `www.youtube.com`, `youtube.com`, `www.youtube-nocookie.com`, `youtube-nocookie.com`, Vimeo `player.vimeo.com`).
+- `<div>` wrappers are treated as iframe-type embeds only when the same HTML block contains an `<iframe ...>` tag (for example common video wrapper markup).
+- `videoWithoutCaption` enables captionless wrapping for `<video>` blocks and for iframes (including those nested in `<div>` wrappers) whose `src` host is a known YouTube/Vimeo provider. `iframeWithoutCaption` also enables captionless wrapping for iframe candidates generally. A known video iframe keeps the `f-video` classification through either option; a generic iframe requires `iframeWithoutCaption` and uses `f-iframe`.
+- Blockquote-based social embeds (Twitter/X `twitter-tweet`, Mastodon `mastodon-embed`, Bluesky `bluesky-embed`, Instagram `instagram-media`, Threads `text-post-media`) are treated like iframe-type embeds when their class list contains one of those provider classes. Extra classes, `data-*` attributes, inline styles, SVG content, and the embed-script host do not block detection. By default they become `<figure class="f-img">` so the caption label behaves like an image label; quote labels are also accepted. You can override that figure class with `figureClassThatWrapsIframeTypeBlockquote` or the global `allIframeTypeFigureClassName`.
+- `p7d-markdown-it-p-captions` ships with a `Slide.` label. When you use it (for example with Speaker Deck or SlideShare iframes), the `<figure>` wrapper automatically switches to `f-slide` (or whatever you set via `figureClassThatWrapsSlides`) so slides can get their own layout. If `allIframeTypeFigureClassName` is also configured, that class takes precedence even for slides, so you get a uniform embed wrapper without touching the slide option.
+- Other eligible iframe blocks use `<figure class="f-iframe">` unless you override the class via `allIframeTypeFigureClassName`. Eligibility still requires a caption or the corresponding captionless-wrapping option.
+
+### Label span class name
+
+- The label inside the figcaption (the `span` element used for the label) is generated by `p7d-markdown-it-p-captions`, not by this plugin. By default the class name is formed by combining `classPrefix` with the mark name, producing names such as `f-img-label`, `f-video-label`, `f-blockquote-label`, and `f-slide-label`.
+- With `markdown-it-attrs`, attributes attached to image-only paragraphs (for example `![...](...) {.foo #bar}`) are forwarded to the generated `<figure>`.
+- `styleProcess` controls parsing of a trailing `{...}` block from the last text token of an image-only paragraph in this plugin's own scanner. It supports simple `.class`, `#id`, bare attributes, and quoted `key="value with spaces"` / `key='value with spaces'` pairs. It is still a narrow fallback parser, not full `markdown-it-attrs` parity, and attributes already attached to paragraph tokens by `markdown-it-attrs` are still forwarded.
+- Attribute forwarding is not sanitization. If you render untrusted Markdown, keep using an HTML sanitizer or a trusted-host policy appropriate for your application; this plugin only decides which already-parsed or narrowly parsed attributes move onto `<figure>`.
+- Attributes attached to caption paragraphs stay on the converted `<figcaption>` token after paragraph-to-figcaption conversion.
+
+## Behavior Customization
+
+### Styles
+
+- Set `allIframeTypeFigureClassName: 'f-embed'` (recommended) to force a single CSS class across `<iframe>` and social-embed figures so they can share styles, ensuring every embed wrapper shares the same predictable class name.
+- `figureClassThatWrapsIframeTypeBlockquote`: override the class used when recognized blockquote-based embeds (Twitter/X, Mastodon, Bluesky, Instagram, Threads) are wrapped.
+- `figureClassThatWrapsSlides`: override the class assigned when a caption paragraph uses the `Slide.` label.
+- `classPrefix` (default `f`) controls the CSS namespace for generated default classes (`f-img`, `f-table`, etc.) so you can align with existing styles. Explicit wrapper-class overrides remain independent.
+- Wrapper/class-prefix options are trimmed during setup; whitespace-only values fall back to the default class for that option.
+
+### Wrapping without captions
+
+- `imageOnlyParagraphWithoutCaption`: turn valid image-only paragraphs into `<figure>` elements even when no caption paragraph/auto caption is present. This includes single-image paragraphs and, when `multipleImages` is enabled, multi-image paragraphs that receive classes such as `f-img-horizontal`, `f-img-vertical`, or `f-img-multiple`. This is independent of automatic detection.
+- `oneImageWithoutCaption`: legacy alias for `imageOnlyParagraphWithoutCaption`. When both are provided, `imageOnlyParagraphWithoutCaption` wins.
+- `videoWithoutCaption`, `audioWithoutCaption`, `iframeWithoutCaption`, `iframeTypeBlockquoteWithoutCaption`: wrap the respective media blocks without caption.
+
+### Caption text helpers (integrated with `p7d-markdown-it-p-captions`)
+
+`p7d-markdown-it-p-captions` owns caption parsing and figcaption rendering for
+the options below. This plugin normalizes the values that also affect figure
+selection, numbering, or final wrapper-class integration before passing the
+shared option state to p-captions:
+
+- `strongFilename` / `dquoteFilename`: pull out filenames from captions using `**filename**` or `"filename"` syntax and wrap them in `<strong class="f-*-filename">`.
+- `jointSpaceUseHalfWidth`: replace full-width space between Japanese labels and caption body with half-width space.
+- `bLabel` / `strongLabel`: emphasize the label span itself.
+- `removeUnnumberedLabel`: drop the leading label entirely when no label number is present. Use `removeUnnumberedLabelExceptMarks` to keep specific labels (e.g., `['blockquote']` keeps `Quote. `).
+- `removeMarkNameInCaptionClass`: replace `.f-img-label` / `.f-table-label` with the generic `.f-label`.
+- `wrapCaptionBody`: wrap the non-label caption text in a span element.
+- `hasNumClass`: add a class attribute to a label span when the source caption has a label number. For compatibility with the pre-shared-engine pipeline, numbers generated by this figure plugin do not retroactively add `label-has-num`.
+- `labelClassFollowsFigure`: mirror the final resolved `<figure>` class onto the `figcaption` spans (`f-embed-label`, `f-embed-label-joint`, `f-embed-body`, etc.) when you want captions styled alongside the wrapper. Caption-driven slide classes are resolved before span construction, including custom `figureClassThatWrapsSlides` values.
+- `figureToLabelClassMap`: extend `labelClassFollowsFigure` by mapping specific final figure classes (e.g., `f-embed` or `f-slide`) to custom caption label classes such as `caption-embed caption-social` for fine-grained control. When this map is provided and `labelClassFollowsFigure` is not set explicitly, figure-following mode is enabled automatically.
+- `labelPrefixMarker`: allow a leading marker before labels (string or array, e.g., `*Figure. ...`). Arrays are limited to two markers; extras are ignored.
+- `allowLabelPrefixMarkerWithoutLabel`: accept marker-only caption paragraphs when set to `true`. With a marker array, the first marker applies before a figure and the second after it.
+- `languages`: optional available caption-recognition catalogs delegated to `p7d-markdown-it-p-captions` (default: `['en', 'ja']`). Most users can leave this unset. Set it only when you want to restrict or extend which labels can be recognized (for example English `Figure.` and Japanese `図　`) and which catalogs are available for generated fallback labels. It is separate from the active locale used to choose among those available catalogs.
+- Automatic image-label fallback text and punctuation (`Figure. `, `図　`, etc.) are generated from `p7d-markdown-it-p-captions` locale metadata, not from a local hardcoded map in this plugin.
+- Generated fallback label tie-break is resolved lazily, at most once per render, when an image actually needs an unlabeled fallback. Prefer passing the active locale through `env.locale` or `env.preferredLocales`. Compatibility fallbacks are `preferredLanguages`, `env.preferredLanguages`, `env.lang`, and `env.language`. If none of those selects an available catalog, this plugin finally uses a cheap document-script heuristic that skips a leading hyphen-fenced frontmatter block (`---` or longer, spaces allowed before newline), then falls back to the raw `languages` order. This tie-break only affects generated fallback labels; it does not change the caption-recognition dictionaries selected by `languages`. Compatibility note: for generated fallback labels, `env.locale` / `env.preferredLocales` intentionally take precedence over the legacy `preferredLanguages` option so a shared `md` instance can render different documents with different active locales. Laziness is based on the final image token stream rather than raw `![` source text, so image tokens inserted by an earlier core rule receive the same locale behavior.
+
+## Basic Usage
+
+```js
+import mdit from 'markdown-it'
+import mditFigureWithPCaption from '@peaceroad/markdown-it-figure-with-p-caption'
+import mditRendererFence from '@peaceroad/markdown-it-renderer-fence' // optional but keeps fences aligned with samples
+
+const md = mdit({ html: true, langPrefix: 'language-', })
+  .use(mditFigureWithPCaption)
+  .use(mditRendererFence)
+
+console.log(md.render('Figure. A Cat.\n\n![A cat](cat.jpg)'))
+// <figure class="f-img">
+// <figcaption><span class="f-img-label">Figure<span class="f-img-label-joint">.</span></span> A Cat.</figcaption>
+// <img src="cat.jpg" alt="A cat">
+// </figure>
+```
+
+### Recommended options
+
+The canonical practical baseline is kept in the project README under
+[Recommended options](../README.md#recommended-options), where it remains
+visible to new users and is less likely to drift from the quick-start example.
+
+That configuration enables captionless media wrapping, gives iframe-like
+embeds one predictable class, and enables document-wide image/table numbering.
+`removeUnnumberedLabel` is shown separately because it removes labels for every
+caption that still lacks a number. Use `removeUnnumberedLabelExceptMarks` when
+specific unnumbered labels, such as `Quote.` / `Source.`, must remain visible.
+
+For automatic numbering, chapter/appendix scopes, and the public integration
+API, see [Automatic numbering and integration API](numbering.md). For the
+complete input/output samples, see
+[Complete conversion and option examples](examples.md).

package/embeds/detect.js

@@ -8,14 +8,13 @@ const htmlRegCache = new Map()
 const openingClassAttrReg = /^<[^>]*?\bclass=(?:"([^"]*)"|'([^']*)')/i
 const iframeSrcAttrReg = /<iframe\b[^>]*?\bsrc=(?:"([^"]*)"|'([^']*)')/i
 const endBlockquoteScriptReg = /<\/blockquote> *<script[^>]*?><\/script>$/i
-const targetHtmlHintReg = /<(?:video|audio|iframe|blockquote|div)\b/i
+const targetHtmlHintReg = /<(?:video|audio|iframe|blockquote|div)(?=[\s>])/i
 const blueskyEmbedHintReg = /bluesky-embed/i
-const videoTagHintReg = /<video\b/i
-const audioTagHintReg = /<audio\b/i
-const iframeTagHintReg = /<iframe\b/i
-const blockquoteTagHintReg = /<blockquote\b/i
-const divTagHintReg = /<div\b/i
-const iframeTagReg = /<iframe(?=[\s>])/i
+const videoTagHintReg = /<video(?=[\s>])/i
+const audioTagHintReg = /<audio(?=[\s>])/i
+const iframeTagHintReg = /<iframe(?=[\s>])/i
+const blockquoteTagHintReg = /<blockquote(?=[\s>])/i
+const divTagHintReg = /<div(?=[\s>])/i
 
 const getHtmlReg = (tag) => {
   const cached = htmlRegCache.get(tag)
@@ -45,42 +44,35 @@ const getHtmlDetectionHints = (content) => {
     hasIframeHint,
     hasBlockquoteHint,
     hasDivHint,
-    hasIframeTag: hasIframeHint || (hasDivHint && iframeTagReg.test(source)),
   }
 }
 
-const appendHtmlBlockNewlineIfNeeded = (token, hasTag) => {
-  if ((hasTag[2] && hasTag[3] !== '\n') || (hasTag[1] !== '\n' && hasTag[2] === undefined)) {
-    token.content += '\n'
-  }
-}
+const needsHtmlBlockNewline = (hasTag) => !!(
+  (hasTag[2] && hasTag[3] !== '\n') ||
+  (hasTag[1] !== '\n' && hasTag[2] === undefined)
+)
 
-const consumeBlockquoteEmbedScript = (tokens, token, startIndex) => {
+const findBlockquoteEmbedScriptTransform = (tokens, token, startIndex) => {
   let addedContent = ''
   let i = startIndex + 1
-  while (i < tokens.length) {
-    const nextToken = tokens[i]
-    if (nextToken.type === 'inline' && endBlockquoteScriptReg.test(nextToken.content)) {
-      addedContent += nextToken.content + '\n'
-      if (tokens[i + 1] && tokens[i + 1].type === 'paragraph_close') {
-        tokens.splice(i + 1, 1)
-      }
-      nextToken.content = ''
-      if (nextToken.children) {
-        for (let j = 0; j < nextToken.children.length; j++) {
-          nextToken.children[j].content = ''
-        }
-      }
-      break
-    }
-    if (nextToken.type === 'paragraph_open') {
-      addedContent += '\n'
-      tokens.splice(i, 1)
-      continue
-    }
+  if (tokens[i] && tokens[i].type === 'paragraph_open') {
+    addedContent = '\n'
     i++
   }
-  token.content += addedContent
+  const inlineToken = tokens[i]
+  if (!inlineToken || inlineToken.type !== 'inline' || !endBlockquoteScriptReg.test(inlineToken.content)) {
+    return null
+  }
+  addedContent += inlineToken.content + '\n'
+  let endIndex = i
+  if (tokens[i + 1] && tokens[i + 1].type === 'paragraph_close') endIndex++
+  return {
+    type: 'merge-blockquote-script',
+    token,
+    startIndex,
+    endIndex,
+    addedContent,
+  }
 }
 
 const getOpeningAttrValue = (content, reg) => {
@@ -121,27 +113,39 @@ const isKnownVideoIframe = (content) => {
 }
 
 const detectHtmlTagCandidate = (tokens, token, startIndex, detector, hints) => {
-  if (detector.requiresIframeTag && !hints.hasIframeTag) return ''
+  if (detector.requiresIframeTag && !hints.hasIframeHint) return null
   const hasTagHint = !!(detector.hintKey && hints[detector.hintKey])
   const allowBlueskyFallback = detector.candidate === 'blockquote' && hints.hasBlueskyHint
-  if (!hasTagHint && !allowBlueskyFallback) return ''
+  if (!hasTagHint && !allowBlueskyFallback) return null
   const hasTag = hasTagHint ? token.content.match(getHtmlReg(detector.lookupTag)) : null
   const isBlueskyFallback = detector.candidate === 'blockquote' && !hasTag && hints.hasBlueskyHint
-  if (!hasTag && !isBlueskyFallback) return ''
+  if (!hasTag && !isBlueskyFallback) return null
   if (hasTag) {
-    appendHtmlBlockNewlineIfNeeded(token, hasTag)
-    return detector.matchedTag || detector.candidate
+    return {
+      matchedTag: detector.matchedTag || detector.candidate,
+      endIndex: startIndex,
+      transform: needsHtmlBlockNewline(hasTag)
+        ? { type: 'append-newline', token }
+        : null,
+    }
   }
-  consumeBlockquoteEmbedScript(tokens, token, startIndex)
-  return 'blockquote'
+  const transform = findBlockquoteEmbedScriptTransform(tokens, token, startIndex)
+  return transform
+    ? { matchedTag: 'blockquote', endIndex: transform.endIndex, transform }
+    : null
 }
 
-const resolveHtmlWrapWithoutCaption = (matchedTag, result, htmlWrapWithoutCaption) => {
+const resolveHtmlWrapWithoutCaption = (
+  matchedTag,
+  isVideoIframe,
+  isIframeTypeBlockquote,
+  htmlWrapWithoutCaption,
+) => {
   if (!htmlWrapWithoutCaption) return false
   if (matchedTag === 'blockquote') {
-    return !!(result.isIframeTypeBlockquote && htmlWrapWithoutCaption.iframeTypeBlockquote)
+    return !!(isIframeTypeBlockquote && htmlWrapWithoutCaption.iframeTypeBlockquote)
   }
-  if (matchedTag === 'iframe' && result.isVideoIframe) {
+  if (matchedTag === 'iframe' && isVideoIframe) {
     return !!(htmlWrapWithoutCaption.video || htmlWrapWithoutCaption.iframe)
   }
   return !!htmlWrapWithoutCaption[matchedTag]
@@ -152,35 +156,53 @@ export const detectHtmlFigureCandidate = (tokens, token, startIndex, htmlWrapWit
   const hints = getHtmlDetectionHints(token.content)
   if (!hints) return null
 
-  const result = {
-    isVideoIframe: false,
-    isIframeTypeBlockquote: false,
-  }
-
-  let matchedTag = ''
+  let candidate = null
   for (let i = 0; i < HTML_EMBED_CANDIDATES.length; i++) {
-    matchedTag = detectHtmlTagCandidate(tokens, token, startIndex, HTML_EMBED_CANDIDATES[i], hints)
-    if (matchedTag) break
+    candidate = detectHtmlTagCandidate(tokens, token, startIndex, HTML_EMBED_CANDIDATES[i], hints)
+    if (candidate) break
   }
-  if (!matchedTag) return null
+  if (!candidate) return null
+  const matchedTag = candidate.matchedTag
+  let isIframeTypeBlockquote = false
 
   if (matchedTag === 'blockquote') {
     if (!hasKnownBlockquoteEmbedClass(token.content)) return null
-    result.isIframeTypeBlockquote = true
-  }
-
-  if (matchedTag === 'iframe' && isKnownVideoIframe(token.content)) {
-    result.isVideoIframe = true
+    isIframeTypeBlockquote = true
   }
+  const isVideoIframe = matchedTag === 'iframe' && isKnownVideoIframe(token.content)
 
   return {
     type: 'html',
     tagName: matchedTag,
-    en: startIndex,
+    en: candidate.endIndex,
     replaceInsteadOfWrap: false,
-    wrapWithoutCaption: resolveHtmlWrapWithoutCaption(matchedTag, result, htmlWrapWithoutCaption),
+    wrapWithoutCaption: resolveHtmlWrapWithoutCaption(
+      matchedTag,
+      isVideoIframe,
+      isIframeTypeBlockquote,
+      htmlWrapWithoutCaption,
+    ),
     canWrap: true,
-    isVideoIframe: result.isVideoIframe,
-    isIframeTypeBlockquote: result.isIframeTypeBlockquote,
+    isVideoIframe,
+    isIframeTypeBlockquote,
+    transform: candidate.transform,
+  }
+}
+
+export const applyHtmlFigureTransform = (tokens, detection) => {
+  const transform = detection && detection.transform
+  if (!transform) return detection ? detection.en : 0
+  detection.transform = null
+  if (transform.type === 'append-newline') {
+    transform.token.content += '\n'
+    return detection.en
+  }
+  if (transform.type === 'merge-blockquote-script') {
+    transform.token.content += transform.addedContent
+    const removeCount = transform.endIndex - transform.startIndex
+    if (removeCount > 0) tokens.splice(transform.startIndex + 1, removeCount)
+    detection.en = transform.startIndex
+    return detection.en
   }
+  return detection.en
 }