@diplodoc/transform 4.77.15 → 4.78.0

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import type Token from 'markdown-it/lib/token';
 import type { OptionsType, OutputType } from './typings';
+import type { ContentAudience as VisibilityContentAudience, VisibilityMode as VisibilityContentMode } from './plugins/visibility';
 type TokensOptionsType = OptionsType & {
     tokens: true;
 };
@@ -9,4 +10,6 @@ export = transform;
 declare namespace transform {
     type Options = OptionsType;
     type Output = OutputType;
+    type ContentAudience = VisibilityContentAudience;
+    type VisibilityMode = VisibilityContentMode;
 }

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/transform/index.ts"],"names":[],"mappings":";;;;AAGA,iCAA2B;AAE3B,+BAA0B;AAC1B,sDAAsC;AACtC,8CAAkC;AAElC,SAAS,WAAW,CAAC,KAAa,EAAE,OAAoB;IACpD,MAAM,EACF,IAAI,GAAG,EAAE,EACT,IAAI,EACJ,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,GACrB,GAAG,OAAO,CAAC;IAEZ,OAAO,aAAa,IAAI,UAAU;QAC9B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAA,gBAAc,EAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAC,gBAAgB,EAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,IAAa;IAC9C,SAAG,CAAC,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAC,CAAC,OAAO,IAAA,YAAI,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAE9D,MAAM,KAAK,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,GAAY;IAC1C,OAAO;QACH,MAAM,EAAE,EAAC,GAAG,GAAG,EAAE,IAAI,EAAC;QACtB,IAAI,EAAE,SAAG,CAAC,GAAG,EAAE;KAClB,CAAC;AACN,CAAC;AAMD,SAAS,SAAS,CAAC,WAAmB,EAAE,UAAuB,EAAE;IAC7D,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,EAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAC,GAAG,IAAA,YAAc,EAAC,OAAO,CAAC,CAAC;IAEtD,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;AACL,CAAC;AAED,iBAAS,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/transform/index.ts"],"names":[],"mappings":";;;;AAOA,iCAA2B;AAE3B,+BAA0B;AAC1B,sDAAsC;AACtC,8CAAkC;AAElC,SAAS,WAAW,CAAC,KAAa,EAAE,OAAoB;IACpD,MAAM,EACF,IAAI,GAAG,EAAE,EACT,IAAI,EACJ,gBAAgB,GAAG,KAAK,EACxB,aAAa,GAAG,KAAK,EACrB,UAAU,GAAG,KAAK,GACrB,GAAG,OAAO,CAAC;IAEZ,OAAO,aAAa,IAAI,UAAU;QAC9B,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAA,gBAAc,EAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAC,gBAAgB,EAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,IAAa;IAC9C,SAAG,CAAC,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAC,CAAC,OAAO,IAAA,YAAI,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAE9D,MAAM,KAAK,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,GAAY;IAC1C,OAAO;QACH,MAAM,EAAE,EAAC,GAAG,GAAG,EAAE,IAAI,EAAC;QACtB,IAAI,EAAE,SAAG,CAAC,GAAG,EAAE;KAClB,CAAC;AACN,CAAC;AAMD,SAAS,SAAS,CAAC,WAAmB,EAAE,UAAuB,EAAE;IAC7D,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,EAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAC,GAAG,IAAA,YAAc,EAAC,OAAO,CAAC,CAAC;IAEtD,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;AACL,CAAC;AAED,iBAAS,SAAS,CAAC"}

package/lib/plugins/visibility.d.ts

@@ -0,0 +1,42 @@
+import type MarkdownIt from 'markdown-it';
+import type { MarkdownItPluginCb } from './typings';
+export type ContentAudience = 'human' | 'agent';
+export type VisibilityMode = ContentAudience | 'preserve';
+export interface VisibilityError {
+    line: number;
+    value: string;
+    message: string;
+}
+export interface VisibilityOptions {
+    audience?: VisibilityMode;
+    lint?: boolean;
+    onError?: (error: VisibilityError) => void;
+}
+export interface AudienceFilterResult {
+    content: string;
+    audienceSpecificContent: ContentAudience[];
+    originalCharacters: number;
+    filteredCharacters: number;
+    removedCharacters: number;
+    errors: VisibilityError[];
+}
+/**
+ * Creates the audience visibility directive plugin.
+ *
+ * The `preserve` mode tokenizes both audiences without rendering the directive wrapper. It is
+ * intended for source-aware consumers such as the translation pipeline, which retain untouched
+ * source ranges around the emitted content tokens.
+ *
+ * @returns Markdown-it plugin for audience visibility blocks.
+ */
+export declare function visibility({ audience, lint, onError, }?: VisibilityOptions): MarkdownIt.PluginSimple;
+/**
+ * Filters Markdown source for one content audience while preserving all unrelated source text.
+ *
+ * @param markdown Markdown source to filter.
+ * @param audience Audience whose content should be retained.
+ * @returns Filtered source, detected audiences, diagnostics, and character counts.
+ */
+export declare function filterAudienceContent(markdown: string, audience: ContentAudience): AudienceFilterResult;
+declare const visibilityPlugin: MarkdownItPluginCb;
+export default visibilityPlugin;

package/lib/plugins/visibility.js

@@ -0,0 +1,194 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.visibility = visibility;
+exports.filterAudienceContent = filterAudienceContent;
+const markdown_it_1 = __importDefault(require("markdown-it"));
+const directive_1 = require("@diplodoc/directive");
+const AUDIENCE_ORDER = ['human', 'agent'];
+const VISIBILITY_DIRECTIVE_REGEXP = /:{3,}[ \t]*visibility/i;
+function parseAudience(value = '') {
+    return value === 'human' || value === 'agent' ? value : undefined;
+}
+function createVisibilityError(value, line) {
+    const printableValue = value || '<empty>';
+    return {
+        line,
+        value,
+        message: `Invalid visibility audience "${printableValue}" at line ${line}; expected "human" or "agent"`,
+    };
+}
+function addAudience(target, audience) {
+    target.add(audience);
+}
+function orderedAudiences(audiences) {
+    const values = new Set(audiences);
+    return AUDIENCE_ORDER.filter((audience) => values.has(audience));
+}
+function markAudience(state, audience) {
+    var _a;
+    if (!state.env.meta || typeof state.env.meta !== 'object' || Array.isArray(state.env.meta)) {
+        state.env.meta = {};
+    }
+    const meta = state.env.meta;
+    meta.visibilityAudiences = orderedAudiences([...((_a = meta.visibilityAudiences) !== null && _a !== void 0 ? _a : []), audience]);
+}
+function emitLintToken(state, params, audience) {
+    var _a, _b;
+    const token = state.push('__yfm_lint', '', 0);
+    token.hidden = true;
+    token.map = [params.startLine, params.startLine + 1];
+    token.attrSet('visibility-directive', 'true');
+    token.attrSet('visibility-audience', (_b = (_a = params.contentTitle) === null || _a === void 0 ? void 0 : _a.raw) !== null && _b !== void 0 ? _b : '');
+    token.attrSet('YFM023', audience ? 'valid' : 'invalid');
+}
+/**
+ * Creates the audience visibility directive plugin.
+ *
+ * The `preserve` mode tokenizes both audiences without rendering the directive wrapper. It is
+ * intended for source-aware consumers such as the translation pipeline, which retain untouched
+ * source ranges around the emitted content tokens.
+ *
+ * @returns Markdown-it plugin for audience visibility blocks.
+ */
+function visibility({ audience = 'human', lint = false, onError, } = {}) {
+    return (md) => {
+        md.use((0, directive_1.directiveParser)());
+        if (lint) {
+            md.core.ruler.before('block', 'visibility-lint-mode', (state) => {
+                const token = new state.Token('__yfm_lint', '', 0);
+                token.hidden = true;
+                token.attrSet('visibility-parser', 'true');
+                state.tokens.push(token);
+            });
+        }
+        (0, directive_1.registerContainerDirective)(md, 'visibility', (state, params) => {
+            var _a, _b;
+            const rawAudience = (_b = (_a = params.contentTitle) === null || _a === void 0 ? void 0 : _a.raw) !== null && _b !== void 0 ? _b : '';
+            const blockAudience = parseAudience(rawAudience);
+            if (lint) {
+                emitLintToken(state, params, blockAudience);
+            }
+            if (!blockAudience) {
+                onError === null || onError === void 0 ? void 0 : onError(createVisibilityError(rawAudience, params.startLine + 1));
+                if (audience === 'preserve') {
+                    (0, directive_1.tokenizeBlockContent)(state, params.content, 'visibility-directive');
+                }
+                return true;
+            }
+            markAudience(state, blockAudience);
+            if (audience === 'preserve' || audience === blockAudience) {
+                (0, directive_1.tokenizeBlockContent)(state, params.content, 'visibility-directive');
+            }
+            return true;
+        });
+    };
+}
+function splitLines(content) {
+    var _a;
+    return (_a = content.match(/[^\r\n]*(?:\r\n|\n|\r)|[^\r\n]+$/g)) !== null && _a !== void 0 ? _a : [];
+}
+function nestBlocks(blocks) {
+    const roots = [];
+    const stack = [];
+    for (const block of blocks.sort((left, right) => {
+        const startDiff = left.params.startLine - right.params.startLine;
+        return startDiff || right.params.endLine - left.params.endLine;
+    })) {
+        while (stack.length &&
+            block.params.startLine >= stack[stack.length - 1].params.content.endLine) {
+            stack.pop();
+        }
+        const parent = stack[stack.length - 1];
+        if (parent && block.params.endLine <= parent.params.content.endLine) {
+            parent.children.push(block);
+        }
+        else {
+            roots.push(block);
+        }
+        stack.push(block);
+    }
+    return roots;
+}
+function filterRange(lines, startLine, endLine, blocks, selectedAudience) {
+    const parts = [];
+    let cursorLine = startLine;
+    for (const block of blocks) {
+        const { params, audience } = block;
+        parts.push(lines.slice(cursorLine, params.startLine).join(''));
+        const filteredBody = filterRange(lines, params.content.startLine, params.content.endLine, block.children, selectedAudience);
+        if (audience === selectedAudience) {
+            parts.push(filteredBody);
+        }
+        cursorLine = params.endLine;
+    }
+    parts.push(lines.slice(cursorLine, endLine).join(''));
+    return parts.join('');
+}
+/**
+ * Filters Markdown source for one content audience while preserving all unrelated source text.
+ *
+ * @param markdown Markdown source to filter.
+ * @param audience Audience whose content should be retained.
+ * @returns Filtered source, detected audiences, diagnostics, and character counts.
+ */
+function filterAudienceContent(markdown, audience) {
+    const originalCharacters = Array.from(markdown).length;
+    if (!VISIBILITY_DIRECTIVE_REGEXP.test(markdown)) {
+        return {
+            content: markdown,
+            audienceSpecificContent: [],
+            originalCharacters,
+            filteredCharacters: originalCharacters,
+            removedCharacters: 0,
+            errors: [],
+        };
+    }
+    const detectedAudiences = new Set();
+    const errors = [];
+    const blocks = [];
+    const md = new markdown_it_1.default({ html: true }).use((0, directive_1.directiveParser)());
+    (0, directive_1.registerContainerDirective)(md, 'visibility', (state, params) => {
+        var _a, _b;
+        const rawAudience = (_b = (_a = params.contentTitle) === null || _a === void 0 ? void 0 : _a.raw) !== null && _b !== void 0 ? _b : '';
+        const blockAudience = parseAudience(rawAudience);
+        blocks.push({ audience: blockAudience, params, children: [] });
+        if (blockAudience) {
+            addAudience(detectedAudiences, blockAudience);
+        }
+        else {
+            errors.push(createVisibilityError(rawAudience, params.startLine + 1));
+        }
+        // Parse nested directives in the original block state. Their line maps remain relative to
+        // the complete source, so reconstruction below can preserve list indentation exactly.
+        (0, directive_1.tokenizeBlockContent)(state, params.content, 'visibility-directive');
+        return true;
+    });
+    md.parse(markdown, {});
+    const lines = splitLines(markdown);
+    const content = filterRange(lines, 0, lines.length, nestBlocks(blocks), audience);
+    const filteredCharacters = Array.from(content).length;
+    return {
+        content,
+        audienceSpecificContent: orderedAudiences(detectedAudiences),
+        originalCharacters,
+        filteredCharacters,
+        removedCharacters: originalCharacters - filteredCharacters,
+        errors,
+    };
+}
+const visibilityPlugin = (md, options) => {
+    var _a;
+    const lint = options.isLintRun;
+    md.use(visibility({
+        audience: lint ? 'preserve' : ((_a = options.contentAudience) !== null && _a !== void 0 ? _a : 'human'),
+        lint,
+        onError: lint
+            ? undefined
+            : (error) => options.log.error(`${error.message}${options.path ? ` in ${options.path}` : ''}`),
+    }));
+};
+exports.default = visibilityPlugin;
+//# sourceMappingURL=visibility.js.map

package/lib/plugins/visibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.js","sourceRoot":"","sources":["../../src/transform/plugins/visibility.ts"],"names":[],"mappings":"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"}

package/lib/plugins.js

@@ -18,6 +18,7 @@ const imsize_1 = __importDefault(require("./plugins/imsize"));
 const term_1 = __importDefault(require("./plugins/term"));
 const block_anchor_1 = __importDefault(require("./plugins/block-anchor"));
 const inline_code_1 = __importDefault(require("./plugins/inline-code"));
+const visibility_1 = __importDefault(require("./plugins/visibility"));
 const defaultPlugins = [
     meta_1.default,
     deflist_1.default,
@@ -35,6 +36,7 @@ const defaultPlugins = [
     term_1.default,
     block_anchor_1.default,
     inline_code_1.default,
+    visibility_1.default,
 ];
 module.exports = defaultPlugins;
 //# sourceMappingURL=plugins.js.map

package/lib/plugins.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/transform/plugins.ts"],"names":[],"mappings":";;;;AAEA,0DAAkC;AAClC,gEAAwC;AACxC,wDAAgC;AAChC,4DAAoC;AACpC,gEAAwC;AACxC,0DAAkC;AAClC,0DAAkC;AAClC,wDAAgC;AAChC,4DAAoC;AACpC,oEAA4C;AAC5C,4DAAuC;AACvC,0DAAkC;AAClC,8DAAsC;AACtC,0DAAkC;AAClC,0EAAiD;AACjD,wEAA+C;AAE/C,MAAM,cAAc,GAAG;IACnB,cAAI;IACJ,iBAAO;IACP,aAAG;IACH,eAAK;IACL,iBAAO;IACP,cAAI;IACJ,cAAI;IACJ,aAAG;IACH,eAAK;IACL,mBAAS;IACT,eAAQ;IACR,cAAI;IACJ,gBAAM;IACN,cAAI;IACJ,sBAAW;IACX,qBAAU;CACW,CAAC;AAE1B,iBAAS,cAAc,CAAC"}
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/transform/plugins.ts"],"names":[],"mappings":";;;;AAEA,0DAAkC;AAClC,gEAAwC;AACxC,wDAAgC;AAChC,4DAAoC;AACpC,gEAAwC;AACxC,0DAAkC;AAClC,0DAAkC;AAClC,wDAAgC;AAChC,4DAAoC;AACpC,oEAA4C;AAC5C,4DAAuC;AACvC,0DAAkC;AAClC,8DAAsC;AACtC,0DAAkC;AAClC,0EAAiD;AACjD,wEAA+C;AAC/C,sEAA8C;AAE9C,MAAM,cAAc,GAAG;IACnB,cAAI;IACJ,iBAAO;IACP,aAAG;IACH,eAAK;IACL,iBAAO;IACP,cAAI;IACJ,cAAI;IACJ,aAAG;IACH,eAAK;IACL,mBAAS;IACT,eAAQ;IACR,cAAI;IACJ,gBAAM;IACN,cAAI;IACJ,sBAAW;IACX,qBAAU;IACV,oBAAU;CACW,CAAC;AAE1B,iBAAS,cAAc,CAAC"}

package/lib/typings.d.ts

@@ -6,6 +6,7 @@ import type { SanitizeFunction, SanitizeOptions } from './sanitize';
 import type { LogLevels, Logger } from './log';
 import type { ChangelogItem } from './plugins/changelog/types';
 import type { IDGenerator } from './plugins/utils';
+import type { VisibilityMode } from './plugins/visibility';
 export interface MarkdownIt extends DefaultMarkdownIt {
     assets?: string[];
     meta?: string[];
@@ -79,6 +80,10 @@ export interface OptionsType {
      * @default false
      */
     codeLineWrapping?: boolean;
+    /**
+     * Selects audience-specific content. Defaults to `human`.
+     */
+    contentAudience?: VisibilityMode;
     /**
      * Custom ID generator factory to use for this transform call.
      * If provided, it will be called once per file to create a per-file isolated generator.
@@ -130,6 +135,7 @@ export interface MarkdownItPluginOpts {
      * the next non-blank line is an `{% include %}` directive.
      */
     multilineTermDefinitions?: boolean;
+    contentAudience?: VisibilityMode;
 }
 export type MarkdownItPluginCb<T extends {} = {}> = {
     (md: MarkdownIt, opts: T & MarkdownItPluginOpts): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diplodoc/transform",
-  "version": "4.77.15",
+  "version": "4.78.0",
   "description": "A simple transformer of text in YFM (Yandex Flavored Markdown) to HTML",
   "keywords": [
     "markdown",
@@ -54,8 +54,9 @@
   },
   "dependencies": {
     "@diplodoc/cut-extension": "^1.1.6",
+    "@diplodoc/directive": "^0.4.0",
     "@diplodoc/file-extension": "^0.2.5",
-    "@diplodoc/tabs-extension": "^3.10.5",
+    "@diplodoc/tabs-extension": "^3.10.7",
     "@diplodoc/utils": "^2.3.5",
     "chalk": "^4.1.2",
     "cheerio": "^1.0.0",

package/src/transform/index.ts

@@ -1,5 +1,9 @@
 import type Token from 'markdown-it/lib/token';
 import type {EnvType, OptionsType, OutputType} from './typings';
+import type {
+    ContentAudience as VisibilityContentAudience,
+    VisibilityMode as VisibilityContentMode,
+} from './plugins/visibility';
 
 import {bold} from 'chalk';
 
@@ -59,4 +63,6 @@ export = transform;
 namespace transform {
     export type Options = OptionsType;
     export type Output = OutputType;
+    export type ContentAudience = VisibilityContentAudience;
+    export type VisibilityMode = VisibilityContentMode;
 }

package/src/transform/plugins/visibility.ts

@@ -0,0 +1,281 @@
+import type MarkdownIt from 'markdown-it';
+import type StateBlock from 'markdown-it/lib/rules_block/state_block';
+import type {ContainerDirectiveParams} from '@diplodoc/directive';
+import type {MarkdownItPluginCb} from './typings';
+
+import MarkdownItImpl from 'markdown-it';
+import {
+    directiveParser,
+    registerContainerDirective,
+    tokenizeBlockContent,
+} from '@diplodoc/directive';
+
+export type ContentAudience = 'human' | 'agent';
+export type VisibilityMode = ContentAudience | 'preserve';
+
+export interface VisibilityError {
+    line: number;
+    value: string;
+    message: string;
+}
+
+export interface VisibilityOptions {
+    audience?: VisibilityMode;
+    lint?: boolean;
+    onError?: (error: VisibilityError) => void;
+}
+
+export interface AudienceFilterResult {
+    content: string;
+    audienceSpecificContent: ContentAudience[];
+    originalCharacters: number;
+    filteredCharacters: number;
+    removedCharacters: number;
+    errors: VisibilityError[];
+}
+
+type VisibilityMeta = Record<string, unknown> & {
+    visibilityAudiences?: ContentAudience[];
+};
+
+type VisibilityBlock = {
+    audience?: ContentAudience;
+    params: ContainerDirectiveParams;
+    children: VisibilityBlock[];
+};
+
+const AUDIENCE_ORDER: ContentAudience[] = ['human', 'agent'];
+const VISIBILITY_DIRECTIVE_REGEXP = /:{3,}[ \t]*visibility/i;
+
+function parseAudience(value = ''): ContentAudience | undefined {
+    return value === 'human' || value === 'agent' ? value : undefined;
+}
+
+function createVisibilityError(value: string, line: number): VisibilityError {
+    const printableValue = value || '<empty>';
+    return {
+        line,
+        value,
+        message: `Invalid visibility audience "${printableValue}" at line ${line}; expected "human" or "agent"`,
+    };
+}
+
+function addAudience(target: Set<ContentAudience>, audience: ContentAudience): void {
+    target.add(audience);
+}
+
+function orderedAudiences(audiences: Iterable<ContentAudience>): ContentAudience[] {
+    const values = new Set(audiences);
+    return AUDIENCE_ORDER.filter((audience) => values.has(audience));
+}
+
+function markAudience(state: StateBlock, audience: ContentAudience): void {
+    if (!state.env.meta || typeof state.env.meta !== 'object' || Array.isArray(state.env.meta)) {
+        state.env.meta = {};
+    }
+    const meta = state.env.meta as VisibilityMeta;
+    meta.visibilityAudiences = orderedAudiences([...(meta.visibilityAudiences ?? []), audience]);
+}
+
+function emitLintToken(
+    state: StateBlock,
+    params: ContainerDirectiveParams,
+    audience: ContentAudience | undefined,
+): void {
+    const token = state.push('__yfm_lint', '', 0);
+    token.hidden = true;
+    token.map = [params.startLine, params.startLine + 1];
+    token.attrSet('visibility-directive', 'true');
+    token.attrSet('visibility-audience', params.contentTitle?.raw ?? '');
+    token.attrSet('YFM023', audience ? 'valid' : 'invalid');
+}
+
+/**
+ * Creates the audience visibility directive plugin.
+ *
+ * The `preserve` mode tokenizes both audiences without rendering the directive wrapper. It is
+ * intended for source-aware consumers such as the translation pipeline, which retain untouched
+ * source ranges around the emitted content tokens.
+ *
+ * @returns Markdown-it plugin for audience visibility blocks.
+ */
+export function visibility({
+    audience = 'human',
+    lint = false,
+    onError,
+}: VisibilityOptions = {}): MarkdownIt.PluginSimple {
+    return (md) => {
+        md.use(directiveParser());
+        if (lint) {
+            md.core.ruler.before('block', 'visibility-lint-mode', (state) => {
+                const token = new state.Token('__yfm_lint', '', 0);
+                token.hidden = true;
+                token.attrSet('visibility-parser', 'true');
+                state.tokens.push(token);
+            });
+        }
+        registerContainerDirective(md, 'visibility', (state, params) => {
+            const rawAudience = params.contentTitle?.raw ?? '';
+            const blockAudience = parseAudience(rawAudience);
+
+            if (lint) {
+                emitLintToken(state, params, blockAudience);
+            }
+
+            if (!blockAudience) {
+                onError?.(createVisibilityError(rawAudience, params.startLine + 1));
+                if (audience === 'preserve') {
+                    tokenizeBlockContent(state, params.content, 'visibility-directive');
+                }
+                return true;
+            }
+
+            markAudience(state, blockAudience);
+
+            if (audience === 'preserve' || audience === blockAudience) {
+                tokenizeBlockContent(state, params.content, 'visibility-directive');
+            }
+
+            return true;
+        });
+    };
+}
+
+function splitLines(content: string): string[] {
+    return content.match(/[^\r\n]*(?:\r\n|\n|\r)|[^\r\n]+$/g) ?? [];
+}
+
+function nestBlocks(blocks: VisibilityBlock[]): VisibilityBlock[] {
+    const roots: VisibilityBlock[] = [];
+    const stack: VisibilityBlock[] = [];
+
+    for (const block of blocks.sort((left, right) => {
+        const startDiff = left.params.startLine - right.params.startLine;
+        return startDiff || right.params.endLine - left.params.endLine;
+    })) {
+        while (
+            stack.length &&
+            block.params.startLine >= stack[stack.length - 1].params.content.endLine
+        ) {
+            stack.pop();
+        }
+
+        const parent = stack[stack.length - 1];
+        if (parent && block.params.endLine <= parent.params.content.endLine) {
+            parent.children.push(block);
+        } else {
+            roots.push(block);
+        }
+        stack.push(block);
+    }
+
+    return roots;
+}
+
+function filterRange(
+    lines: string[],
+    startLine: number,
+    endLine: number,
+    blocks: VisibilityBlock[],
+    selectedAudience: ContentAudience,
+): string {
+    const parts: string[] = [];
+    let cursorLine = startLine;
+
+    for (const block of blocks) {
+        const {params, audience} = block;
+        parts.push(lines.slice(cursorLine, params.startLine).join(''));
+        const filteredBody = filterRange(
+            lines,
+            params.content.startLine,
+            params.content.endLine,
+            block.children,
+            selectedAudience,
+        );
+        if (audience === selectedAudience) {
+            parts.push(filteredBody);
+        }
+        cursorLine = params.endLine;
+    }
+
+    parts.push(lines.slice(cursorLine, endLine).join(''));
+    return parts.join('');
+}
+
+/**
+ * Filters Markdown source for one content audience while preserving all unrelated source text.
+ *
+ * @param markdown Markdown source to filter.
+ * @param audience Audience whose content should be retained.
+ * @returns Filtered source, detected audiences, diagnostics, and character counts.
+ */
+export function filterAudienceContent(
+    markdown: string,
+    audience: ContentAudience,
+): AudienceFilterResult {
+    const originalCharacters = Array.from(markdown).length;
+    if (!VISIBILITY_DIRECTIVE_REGEXP.test(markdown)) {
+        return {
+            content: markdown,
+            audienceSpecificContent: [],
+            originalCharacters,
+            filteredCharacters: originalCharacters,
+            removedCharacters: 0,
+            errors: [],
+        };
+    }
+
+    const detectedAudiences = new Set<ContentAudience>();
+    const errors: VisibilityError[] = [];
+    const blocks: VisibilityBlock[] = [];
+    const md = new MarkdownItImpl({html: true}).use(directiveParser());
+
+    registerContainerDirective(md, 'visibility', (state, params) => {
+        const rawAudience = params.contentTitle?.raw ?? '';
+        const blockAudience = parseAudience(rawAudience);
+        blocks.push({audience: blockAudience, params, children: []});
+
+        if (blockAudience) {
+            addAudience(detectedAudiences, blockAudience);
+        } else {
+            errors.push(createVisibilityError(rawAudience, params.startLine + 1));
+        }
+
+        // Parse nested directives in the original block state. Their line maps remain relative to
+        // the complete source, so reconstruction below can preserve list indentation exactly.
+        tokenizeBlockContent(state, params.content, 'visibility-directive');
+        return true;
+    });
+
+    md.parse(markdown, {});
+    const lines = splitLines(markdown);
+    const content = filterRange(lines, 0, lines.length, nestBlocks(blocks), audience);
+    const filteredCharacters = Array.from(content).length;
+
+    return {
+        content,
+        audienceSpecificContent: orderedAudiences(detectedAudiences),
+        originalCharacters,
+        filteredCharacters,
+        removedCharacters: originalCharacters - filteredCharacters,
+        errors,
+    };
+}
+
+const visibilityPlugin: MarkdownItPluginCb = (md, options) => {
+    const lint = options.isLintRun;
+    md.use(
+        visibility({
+            audience: lint ? 'preserve' : (options.contentAudience ?? 'human'),
+            lint,
+            onError: lint
+                ? undefined
+                : (error) =>
+                      options.log.error(
+                          `${error.message}${options.path ? ` in ${options.path}` : ''}`,
+                      ),
+        }),
+    );
+};
+
+export default visibilityPlugin;

package/src/transform/plugins.ts

@@ -16,6 +16,7 @@ import imsize from './plugins/imsize';
 import term from './plugins/term';
 import blockAnchor from './plugins/block-anchor';
 import inlineCode from './plugins/inline-code';
+import visibility from './plugins/visibility';
 
 const defaultPlugins = [
     meta,
@@ -34,6 +35,7 @@ const defaultPlugins = [
     term,
     blockAnchor,
     inlineCode,
+    visibility,
 ] as MarkdownItPluginCb[];
 
 export = defaultPlugins;