@inditextech/docouture-asciidoc-extensions 0.1.0-SNAPSHOT.40.1

package/lib/nowrap-cols.js

@@ -0,0 +1,61 @@
+'use strict'
+
+// `[cols="1,3,2",nowrap-cols="1,2"]` — an author-facing way to pin
+// `white-space: nowrap` to specific columns (e.g. a mono-token column that
+// should never break mid-value), without a new inline macro: `m|`/`mono:`
+// already exist for "this cell is code" and neither carries a per-COLUMN
+// concept, and the html5 converter hardcodes cell class to
+// `tableblock halign-* valign-*` (see doc.css's own `td.tableblock`
+// comment) — no room there either. A tree processor turning the attribute
+// into roles is the only hook that reaches the table node itself before it
+// converts to `<table class="tableblock …">`.
+//
+// `nowrap-cols="*"` (or any non-numeric token) is rejected per-token with a
+// warning rather than silently doing nothing — a typo'd column index should
+// fail loudly. Valid range is 1-12: doc.css only ever ships nth-child rules
+// up to that ceiling (comfortably past any real `cols=` in this codebase),
+// and a document needing more is almost certainly better served by
+// `[cols=]`'s own per-column `.nowrap` role below instead (every column).
+const MAX_COLS = 12
+const NOWRAP_ALL_ATTR = 'nowrap' // `[cols=...,%nowrap]` shorthand — every column
+
+function parseColumnIndexes(raw, doc, table) {
+  const logger = doc.getLogger()
+  const indexes = []
+  raw
+    .split(',')
+    .map((token) => token.trim())
+    .filter(Boolean)
+    .forEach((token) => {
+      const n = Number(token)
+      if (!Number.isInteger(n) || n < 1 || n > MAX_COLS) {
+        logger.warn(
+          'nowrap-cols="' +
+            raw +
+            '" on table "' +
+            (table.getTitle() || '(untitled)') +
+            '" — ignoring invalid column "' +
+            token +
+            '"; expected an integer between 1 and ' +
+            MAX_COLS
+        )
+        return
+      }
+      indexes.push(n)
+    })
+  return indexes
+}
+
+module.exports = function registerNowrapCols(registry) {
+  registry.treeProcessor(function () {
+    this.process(function (doc) {
+      doc.findBy({ context: 'table' }).forEach((table) => {
+        if (table.hasAttribute(NOWRAP_ALL_ATTR)) table.addRole('nowrap')
+        const raw = table.getAttribute('nowrap-cols')
+        if (!raw) return
+        parseColumnIndexes(String(raw), doc, table).forEach((n) => table.addRole('nowrap-' + n))
+      })
+      return doc
+    })
+  })
+}

package/lib/shiki-config.js

@@ -0,0 +1,94 @@
+'use strict'
+
+// Shared config between the two halves of the Shiki (GH-89) syntax
+// highlighter: `shiki-prewarm.js` (an @inditextech/docouture-antora-extensions
+// pipeline extension, builds the one shared highlighter instance
+// asynchronously before any page converts) and `shiki-syntax-highlighter.js`
+// (the Asciidoctor SyntaxHighlighter adapter that reads it back
+// synchronously, once per source block). Both need the exact same language
+// and theme set — if the prewarm loads a language the highlighter never
+// asks for, or vice versa, `getLoadedLanguages()` and the actual grammar set
+// silently disagree.
+
+module.exports = {
+  // Shiki's "css variables" dual-theme mode (`defaultColor: false` — see
+  // shiki-syntax-highlighter.js) emits `--shiki-light`/`--shiki-dark` custom
+  // properties instead of literal colours; ui-bundle's doc.css switches
+  // between them on `.ids-theme-dark`, the same toggle the rest of the site
+  // themes off. Named themes, not hljs's theme FILES (GH-12) — @shikijs/themes
+  // ships them as data, no CSS import/PostCSS scoping step needed at all.
+  //
+  // Both slots are the SAME theme — deliberately, not an oversight. The
+  // code surface itself (doc.css) is black in EITHER site theme by design
+  // (GH-12 again: the design keeps a dark code surface regardless of
+  // light/dark site mode), so there is no separate "light" palette to
+  // switch to in the first place — a genuinely light-background theme
+  // (tried: 'github-light') renders near-illegible dark-grey text on that
+  // black surface (verified empirically). 'github-dark'/'github-dark-dimmed'
+  // (matching hljs's own old GH-12 pairing) and 'monokai' were tried next
+  // and both worked; settled on 'dark-plus' — Shiki's bundled name for VS
+  // Code's own default "Dark+" theme (GH-89 follow-up request) — for the
+  // familiarity of VS Code's own colour choices. One name in both slots
+  // means the code blocks look identical regardless of site theme —
+  // intentional, not a placeholder half-migration.
+  LIGHT_THEME: 'dark-plus',
+  DARK_THEME: 'dark-plus',
+
+  // @shikijs/langs module ids to bundle into the one synchronous highlighter
+  // instance — see shiki-prewarm.js's own header for why this must be a
+  // fixed, synchronously-loadable list rather than Shiki's normal on-demand
+  // dynamic import. Mirrors the language set
+  // ui-bundle/src/js/vendor/highlight.bundle.ts used to register under
+  // highlight.js, plus 'html', 'typescript' and 'tsx' — actually used by
+  // authored content (`[source,html]`, `[source,ts]`, `[source,tsx]`) but
+  // never registered under the old hljs bundle, so those three blocks were
+  // never really syntax-highlighted before this.
+  LANGS: [
+    'asciidoc',
+    'bash',
+    'clojure',
+    'cpp',
+    'csharp',
+    'css',
+    'diff',
+    'dockerfile',
+    'elixir',
+    'go',
+    'groovy',
+    'haskell',
+    'html',
+    'java',
+    'javascript',
+    'json',
+    'julia',
+    'kotlin',
+    'lua',
+    'markdown',
+    'nix',
+    'objective-c',
+    'perl',
+    'php',
+    'properties',
+    'puppet',
+    'python',
+    'ruby',
+    'rust',
+    'scala',
+    'shell',
+    'sql',
+    'swift',
+    'tsx',
+    'typescript',
+    'xml',
+    'yaml',
+  ],
+
+  // hljs's own name for a grammar Shiki registers under a different id.
+  // highlight.js's objectivec.js self-registers as 'objectivec' with alias
+  // 'objc'; Shiki's equivalent grammar is 'objective-c' (aliased to 'objc',
+  // not 'objectivec') — so `[source,objectivec]`, if ever authored, needs an
+  // explicit redirect. 'ts'/'tsx'/'js' need no entry here: Shiki auto-registers
+  // a loaded grammar's own `aliases` (typescript's include 'ts', 'cts', 'mts'),
+  // so `getLoadedLanguages()` already reports them once 'typescript' loads.
+  LANG_ALIASES: { objectivec: 'objective-c' },
+}

package/lib/shiki-instance.js

@@ -0,0 +1,64 @@
+'use strict'
+
+// Shared handle to the one Shiki highlighter instance for an entire Antora
+// build.
+//
+// `shiki-prewarm.js` — an @inditextech/docouture-antora-extensions PIPELINE
+// extension, hooking Antora's own generator lifecycle — creates it exactly
+// once, asynchronously, before any page is converted. This file's
+// `highlight()` counterpart in shiki-syntax-highlighter.js is an ASCIIDOCTOR
+// extension instead: called synchronously, per source block, by
+// @asciidoctor/core 2.2's fully-synchronous Opal conversion loop, which
+// cannot itself await anything (see asciidoc-extensions/lib/async-compat.js
+// for the first instance of that exact constraint). Splitting the async
+// setup from the sync use is GH-89's whole answer to the issue's own "Key
+// Risk / Spike Required" section — this module is the seam between the two
+// halves, since they live in different packages and are wired into the
+// build by different playbook keys (`antora.extensions` vs
+// `asciidoc.extensions`).
+//
+// A plain module-level variable is enough: @antora/site-generator runs one
+// build per process (see `just build-site`), so there is exactly one
+// instance to hold, and both packages `require()` the exact same file (node's
+// module cache, not a singleton class) — no DI container needed.
+let state = null
+
+module.exports = {
+  /**
+   * Called once by shiki-prewarm.js, after its async Shiki setup resolves.
+   *
+   * @param {object} highlighter - the synchronous-capable Shiki core
+   *   instance (`createHighlighterCoreSync`, built from an
+   *   already-instantiated engine — see that file). Typed loosely as
+   *   `object`, not `import('shiki/core').HighlighterCore`: shiki ships ESM-
+   *   only types, and importing an ESM type from this CommonJS package needs
+   *   a `resolution-mode` assertion this tsconfig doesn't carry — not worth
+   *   adding for one call site when `noImplicitAny`/`noImplicitThis` are
+   *   already off package-wide (see tsconfig.json's own header).
+   * @param {string} rootStyle - the `style` attribute value Shiki itself puts
+   *   on the `<pre>` it generates for a throwaway probe block — the
+   *   `--shiki-light`/`--shiki-dark`/`-*-bg` custom property declarations
+   *   that carry each theme's default foreground/background. Needed because
+   *   `highlight()` returns only the INNER content of the `<code>`
+   *   Asciidoctor wraps it in (see that file's own header for why) — those
+   *   declarations, which normally live on the `<pre>` element Shiki
+   *   generates itself, have nowhere to go, so `highlight()` re-declares them
+   *   verbatim on its own outermost wrapper span instead of trying to parse
+   *   them back out of markup it already discarded.
+   * @returns {void}
+   */
+  set(highlighter, rootStyle) {
+    state = { highlighter, rootStyle }
+  },
+
+  /**
+   * @returns {{ highlighter: object, rootStyle: string } | null} `null`
+   *   before the prewarm listener has run — e.g. the ui-bundle preview
+   *   harness, which never registers `@inditextech/docouture-antora-extensions`
+   *   at all (see extensions.md: it has no content catalog and no Antora
+   *   pipeline). `highlight()` degrades to plain escaped text in that case.
+   */
+  get() {
+    return state
+  },
+}

package/lib/shiki-syntax-highlighter.js

@@ -0,0 +1,137 @@
+'use strict'
+
+const { escapeHtml } = require('./html')
+const shikiInstance = require('./shiki-instance')
+const { LIGHT_THEME, DARK_THEME, LANG_ALIASES } = require('./shiki-config')
+
+// Registers a custom Asciidoctor SyntaxHighlighter adapter, 'shiki' (GH-89),
+// against `@asciidoctor/core ~2.2` — the version actually used to convert
+// pages, via `antora@3.1.15` → `@antora/asciidoc-loader` (see
+// .opencode/skills/asciidoc/reference/extensions.md's version table).
+//
+// THIS IS NOT AN `asciidoc.extensions` REGISTRY EXTENSION. Every other
+// module in this package (label-macro.js, card-grid.js, …) is registered
+// through the per-page `registry` object Antora hands `index.js`'s
+// `register(registry)` — see that file's own header. A syntax highlighter is
+// different: Asciidoctor.js exposes it as a GLOBAL, STATIC registry —
+// `Asciidoctor.SyntaxHighlighter.register(name, functions)` — that lives on
+// the `@asciidoctor/core` module object itself, not on any one page's
+// registry instance. Requiring THIS file (done once, at the top of
+// index.js, not inside `registerAll`) performs that global registration
+// exactly once per process, thanks to node's module cache — which is
+// correct here because pnpm dedupes `@asciidoctor/core` to the identical
+// installed `~2.2` package Antora's own require of it resolves to, so both
+// requires return the very same module singleton.
+//
+// `require('@asciidoctor/core')` is a FACTORY in 2.2 (call it to get the
+// real API object) — see extensions.md's "2.2 — factory export" example.
+//
+// Required under an ALIAS ('asciidoctor-core-2.2', see package.json's
+// `dependencies`), not the bare package name: this package's
+// `devDependencies` already pins `@asciidoctor/core` to `~4.0.8` — a
+// TYPE-ONLY dependency the rest of this package's extensions (accordion.js,
+// cta.js, …) annotate their JSDoc against (see tsconfig.json's own header).
+// pnpm can only link ONE physical `node_modules/@asciidoctor/core` per
+// package, so declaring the real `~2.2` runtime dependency under that same
+// bare name would silently replace those files' 4.0 types with 2.2's —
+// verified empirically: it broke typecheck on every `AbstractBlock`
+// reference elsewhere in this package. `npm:` aliasing keeps both physically
+// installed side by side under different names.
+//
+// `2.2`'s own `.d.ts` types the module's export as a namespace object with no
+// call signature, even though the actual JS bridge IS a factory function
+// (verified empirically — the shape 2.2's own README documents, and the same
+// shape `extensions.md`'s version table describes). `/** @type {any} */`
+// bridges that one gap between the shipped types and the real runtime API,
+// deliberately, rather than fighting it with an incorrect type assertion.
+const asciidoctor = /** @type {any} */ (require('asciidoctor-core-2.2'))()
+
+// Shiki always wraps its own output in `<pre class="shiki ..." style="...">
+// <code>...</code></pre>` — there is no lower-level call that returns just
+// the inner tokens. `highlight()` is only allowed to return the STRING that
+// becomes the block's `content` (Asciidoctor's own `format()` — inherited
+// unmodified from `SyntaxHighlighter::Base` since this adapter doesn't
+// override it — wraps that in ITS OWN `<pre class="shiki highlight">
+// <code data-lang="…">…</code></pre>`, which is what ui-bundle's
+// 06-copy-to-clipboard.ts and doc.css actually key off: `pre.highlight` and
+// `code[data-lang]`). So the outer tags Shiki generated have to be stripped
+// back off; this regex depends on the exact shape Shiki 4.x's HTML renderer
+// produces (verified empirically — see this package's README for how to
+// re-check it against a future Shiki upgrade).
+const SHIKI_WRAPPER_RX = /^<pre[^>]*><code[^>]*>([\s\S]*)<\/code>\s*<\/pre>\s*$/
+
+/**
+ * Asciidoctor passes `lang: 'none'` for an unannotated `[source]` block —
+ * the same case highlight.bundle.ts used to alias to its own 'plaintext'
+ * grammar. Shiki needs no grammar loaded at all for this: 'text' is a
+ * reserved id its core always understands, same as 'plain'/'txt' upstream.
+ */
+function resolveLang(lang) {
+  if (!lang || lang === 'none') return 'text'
+  return LANG_ALIASES[lang] || lang
+}
+
+/**
+ * @param {string} source - raw source text, already run through Asciidoctor's
+ *   own callout extraction (this is the value `highlight()` receives, NOT
+ *   `node.getSource()` — using the passed-in `source` rather than reading the
+ *   node directly is what keeps `<1>` callout bubbles in source blocks
+ *   working: Asciidoctor re-inserts their markup into this function's return
+ *   value by string position, matched against `opts.callouts`).
+ */
+function highlightSource(source, lang) {
+  const instance = shikiInstance.get()
+  if (!instance) {
+    // The pre-warm listener (@inditextech/docouture-antora-extensions'
+    // shiki-prewarm.js) never ran — the ui-bundle preview harness, which has
+    // no Antora pipeline at all (see extensions.md), or a future caller that
+    // forgets to list the extension. Degrade to plain escaped text rather
+    // than throwing: a build with `runtime.log.failure_level: warn` should
+    // fail loudly on a real authoring mistake, not on missing highlighting.
+    return escapeHtml(source)
+  }
+  const { highlighter, rootStyle } = instance
+  const resolved = resolveLang(lang)
+  const effective = highlighter.getLoadedLanguages().includes(resolved) ? resolved : 'text'
+  const html = highlighter.codeToHtml(source, {
+    lang: effective,
+    themes: { light: LIGHT_THEME, dark: DARK_THEME },
+    // "CSS variables" dual-theme mode: emits `--shiki-light`/`--shiki-dark`
+    // custom properties per token instead of a literal colour, so ONE build
+    // output serves both the site's light and dark theme — see
+    // ui-bundle/src/css/doc.css's own `--shiki-*` rules for the switch.
+    defaultColor: false,
+  })
+  const match = SHIKI_WRAPPER_RX.exec(html.trim())
+  const inner = match ? match[1] : escapeHtml(source)
+  // Re-declares the default-colour variables Shiki put on its own (now
+  // discarded) `<pre>` — see shiki-instance.js's own header for why this
+  // can't just read them back off `html` on every call instead.
+  return `<span style="${rootStyle}">${inner}</span>`
+}
+
+asciidoctor.SyntaxHighlighter.register('shiki', {
+  handlesHighlighting() {
+    return true
+  },
+  highlight(node, source, lang) {
+    return highlightSource(source, lang)
+  },
+  // Overridden rather than left to `SyntaxHighlighter::Base`'s own default:
+  // that default reads `self.pre_class`, an instance variable ONLY a real
+  // Ruby subclass's `initialize` sets (to its own registered `name`) —
+  // registering a plain JS functions object the way this file does (per
+  // `.register`'s own contract, see the header above) never runs that
+  // Ruby-side `initialize`, so `pre_class` comes back JS `undefined` and
+  // Base's format would literally emit `class="undefined highlight"`
+  // (verified empirically). Reimplementing `format` here sidesteps that
+  // entirely, for one extra benefit: `node.getContent()` — Asciidoctor's own
+  // already-substituted, callout-restored content, i.e. exactly `highlight()`'s
+  // return value above — is read directly, rather than trusting an
+  // ivar-driven default this adapter doesn't fully participate in.
+  format(node, lang, opts) {
+    const preClass = opts && opts.nowrap ? 'shiki highlight nowrap' : 'shiki highlight'
+    const langAttr = lang ? ' data-lang="' + escapeHtml(lang) + '"' : ''
+    return `<pre class="${preClass}"><code${langAttr}>${node.getContent()}</code></pre>`
+  },
+})

package/lib/table-container.js

@@ -0,0 +1,143 @@
+'use strict'
+
+// GH-14 table-sizing follow-up: `display: block` on `table.tableblock` (the
+// old doc.css mechanism) never actually sized the table — it sizes the
+// BLOCK BOX, and a native table lays out its own anonymous table box inside
+// that with `width: auto` (shrink-to-fit), completely ignoring the parent's
+// width. There is no CSS-only fix: the anonymous box isn't selectable, so a
+// real wrapper element is required. This postprocessor is that wrapper.
+//
+// A postprocessor, not a converter override: Antora hard-sets its own HTML5
+// converter (@antora/asciidoc-loader/lib/load-asciidoc.js), so a custom
+// converter would only ever run in the ui-bundle preview harness, not real
+// site builds. A registry-scoped postprocessor runs identically in both
+// (verified against @asciidoctor/core 4.0.8, embedded/standalone: false).
+//
+// Markup emitted, for every `<table class="tableblock …">…</table>`:
+//
+//   <div class="tableblock-wrap">
+//     <div class="title">…</div>                 <!-- hoisted, if present -->
+//     <div class="tablecontainer"><table class="tableblock …">…</table></div>
+//   </div>
+//
+// Two wrapping divs, not one: `.tableblock-wrap` carries the width budget
+// (and the title), `.tablecontainer` is the horizontal-scroll port — kept
+// separate so the title does not scroll away with the table body.
+//
+// The `<caption class="title">` Asciidoctor emits for a `.Table title` is
+// removed and its content re-emitted as a plain `.title` div OUTSIDE the
+// table, at the wrapper's own (budget) width, rather than the table's own
+// (possibly much narrower — `[width=]`/`%autowidth`) width: a caption is
+// laid out as part of the table box it belongs to, so leaving it in place
+// would have it wrap at the table's width instead of the wrapper's.
+//
+// Table/caption detection is a plain regex scan rather than parsing the
+// converted HTML into a DOM: the postprocessor only ever sees Asciidoctor's
+// own machine-generated output, whose `<table class="tableblock …">` /
+// `</table>` shape is fixed, so a depth counter is sufficient and avoids an
+// HTML-parser dependency for a single, narrow substitution.
+const TABLE_OPEN_RX = /<table class="tableblock\b[^"]*"[^>]*>/g
+const TABLE_TAG_RX = /<(\/?)table\b/g
+const CAPTION_RX = /^\n?<caption class="title">([\s\S]*?)<\/caption>\n?/
+// Idempotency guard: if this table is already the direct child of a
+// `.tablecontainer` this same function placed it in, re-running (verified
+// to happen in practice — `gulp preview`'s watch server re-registers this
+// extension globally on every rebuild without restarting the node process,
+// see index.js's own comment) must leave it alone rather than nesting a
+// second `.tableblock-wrap` around the first, each one re-applying (and
+// compounding) the same width cap.
+const ALREADY_WRAPPED_RX = /<div class="tablecontainer">$/
+// `table-width.js`'s own stash key (doc.findBy-order array of per-table
+// literal CSS widths, `null` where the author didn't set one) — read here
+// by the SAME index, since both this scan and that tree processor's
+// `doc.findBy({context:'table'})` walk the document in the same order
+// (verified empirically).
+const { STASH_KEY: WIDTHS_STASH_KEY } = require('./table-width')
+
+function wrapTables(html, widths = []) {
+  let result = ''
+  let cursor = 0
+  let match
+  let tableIndex = -1
+  while ((match = TABLE_OPEN_RX.exec(html))) {
+    tableIndex += 1
+    if (ALREADY_WRAPPED_RX.test(html.slice(0, match.index))) continue
+
+    const openTagEnd = match.index + match[0].length
+    // Depth-count `<table` / `</table>` tags from just past the opening tag
+    // to find THIS table's own matching close tag, tolerating any table
+    // nested inside a cell (a legitimate, if rare, authoring case).
+    TABLE_TAG_RX.lastIndex = openTagEnd
+    let depth = 1
+    let tagMatch
+    let closeEnd = -1
+    while ((tagMatch = TABLE_TAG_RX.exec(html))) {
+      depth += tagMatch[1] ? -1 : 1
+      if (depth === 0) {
+        closeEnd = html.indexOf('>', TABLE_TAG_RX.lastIndex) + 1
+        break
+      }
+    }
+    if (closeEnd === -1 || closeEnd === 0) break // malformed input; leave the rest untouched
+
+    result += html.slice(cursor, match.index)
+    let inner = html.slice(match.index, closeEnd)
+
+    // `table-width.js`'s literal CSS width (e.g. `2000px`) — set as an
+    // inline `style`, which wins over `.stretch`/`.fit-content` (external
+    // stylesheet rules) unconditionally, regardless of specificity, no
+    // `!important` needed. Spliced into the OPEN TAG specifically (not the
+    // whole `inner`, which also contains the table body) so a `style="…"`
+    // the author's own raw HTML passthrough might already carry is
+    // extended rather than clobbered.
+    //
+    // `bodyStart` (where the caption search below begins) is recomputed
+    // from the SPLICED open tag's own new length, not the original
+    // `openTagEnd - match.index` — that offset is in the pre-splice
+    // string's coordinates, and injecting a `style="…"` attribute makes
+    // the tag longer, so re-using it pointed a few characters short of the
+    // real body and silently broke caption hoisting (verified: the caption
+    // regex, anchored at the very start of what it thinks is the body,
+    // stopped matching entirely once a table also had a `table-width`).
+    const width = widths[tableIndex]
+    let bodyStart = openTagEnd - match.index
+    if (width) {
+      const openTag = inner.slice(0, bodyStart)
+      const styledOpenTag = /\sstyle="/.test(openTag)
+        ? openTag.replace(/\sstyle="/, ' style="width:' + width + ';')
+        : openTag.replace(/>$/, ' style="width:' + width + '">')
+      inner = styledOpenTag + inner.slice(bodyStart)
+      bodyStart = styledOpenTag.length
+    }
+
+    let title = null
+    const afterOpenTag = inner.slice(bodyStart)
+    const captionMatch = afterOpenTag.match(CAPTION_RX)
+    if (captionMatch) {
+      title = captionMatch[1]
+      inner = inner.slice(0, bodyStart) + afterOpenTag.slice(captionMatch[0].length)
+    }
+
+    result +=
+      '<div class="tableblock-wrap">' +
+      (title !== null ? '<div class="title">' + title + '</div>' : '') +
+      '<div class="tablecontainer">' +
+      inner +
+      '</div></div>'
+
+    cursor = closeEnd
+    TABLE_OPEN_RX.lastIndex = cursor
+  }
+  result += html.slice(cursor)
+  return result
+}
+
+module.exports = function registerTableContainer(registry) {
+  registry.postprocessor(function () {
+    this.process(function (doc, output) {
+      return wrapTables(output, doc[WIDTHS_STASH_KEY])
+    })
+  })
+}
+
+module.exports.wrapTables = wrapTables

package/lib/table-width.js

@@ -0,0 +1,70 @@
+'use strict'
+
+// `[table-width=2000px,cols="1,1"]` — an explicit, literal CSS width for a
+// table, bypassing Asciidoctor's own `width=` attribute entirely: that
+// attribute is percentage-only and HARD-CLAMPED to 1-100 (verified against
+// `@asciidoctor/core`'s own `table.js` — `width=2000px` parses to the
+// numeric prefix 2000, sees it's `> 100`, and silently resets it to 100,
+// i.e. exactly the unmarked default, `.stretch`). There is no core AsciiDoc
+// syntax for an absolute width on a table; this is a separate, custom
+// attribute for it.
+//
+// A tree processor is the only hook that can read the RAW attribute value
+// before Asciidoctor's own Table constructor has already computed (and
+// clamped) `tablepcwidth` from it — but the built-in html5 converter only
+// ever emits `id`/`class`/the derived `width="N%"` for a `<table>` tag (see
+// its own table-tag-building code), no generic passthrough for an arbitrary
+// attribute to an inline `style`. So this doesn't touch Asciidoctor's own
+// `width` attribute at all (an author can still combine `width=50%` — a
+// PERCENTAGE OF THE inline style set here — with `table-width`, though
+// that's an unusual thing to want) and instead hands the value to
+// table-container.js's postprocessor, the other half of this mechanism,
+// via a plain array stashed on the `doc` object itself: `doc.findBy` (here)
+// and the postprocessor's own table-order HTML scan (table-container.js)
+// walk the document in the same order (verified empirically), so entry `i`
+// in the array is table `i`'s width, `null` where the attribute is absent.
+//
+// Verified in the CSS as already correct for a literal width with no
+// further changes: `table.tableblock` carries no width rule of its own
+// (only `.stretch`/`.fit-content`, both irrelevant once an inline `style`
+// wins over them unconditionally), and `.tablecontainer`'s `overflow-x:
+// auto` scrolls a table wider than `.tableblock-wrap`'s own 150%-capped
+// budget rather than blowing out the page — exactly the "respect the
+// explicit width, but the SURROUNDING box stays capped" behaviour the
+// percentage form already has.
+const ATTR_NAME = 'table-width'
+const VALID_RX = /^\d+(?:\.\d+)?(?:px|rem|em|ch|vw|vh|%)?$/
+const STASH_KEY = '$docoutureTableWidths'
+
+function parseWidth(raw, doc, table) {
+  const trimmed = String(raw).trim()
+  if (!VALID_RX.test(trimmed)) {
+    doc
+      .getLogger()
+      .warn(
+        ATTR_NAME +
+          '="' +
+          raw +
+          '" on table "' +
+          (table.getTitle() || '(untitled)') +
+          '" — ignoring invalid length; expected a plain number (px assumed) or a number with one of px/rem/em/ch/vw/vh/%'
+      )
+    return null
+  }
+  return /\d$/.test(trimmed) ? trimmed + 'px' : trimmed
+}
+
+module.exports = function registerTableWidth(registry) {
+  registry.treeProcessor(function () {
+    this.process(function (doc) {
+      const widths = (doc[STASH_KEY] = [])
+      doc.findBy({ context: 'table' }).forEach((table) => {
+        const raw = table.getAttribute(ATTR_NAME)
+        widths.push(raw ? parseWidth(raw, doc, table) : null)
+      })
+      return doc
+    })
+  })
+}
+
+module.exports.STASH_KEY = STASH_KEY