codependent-render.sty

%% ===================================================================
%% codependent-render.sty — Rendering layer for the codependent package
%% ===================================================================
%% This file contains ALL backref rendering code extracted from
%% codependent.sty (Phase 3 of tracking/rendering separation).
%% It is loaded conditionally by codependent.sty when backrefs are
%% enabled (\ifbool{codep@backrefs}).
%%
%% The rendering layer accesses graph state ONLY through the
%% query API defined in codependent.sty (Section 8a.3a):
%%   \codep@graph@hasrefs, \codep@graph@getdisplay,
%%   \codep@graph@getanchor, \codep@graph@getkind,
%%   \codep@graph@getentitydisplay, \codep@graph@getprintkind,
%%   \codep@graph@getanchorpage, \codep@graph@foreachref.
%% It does NOT read codep@brcount@, codep@brnode@, or
%% codep@anchor@ directly.  Rendering-specific pgfkeys
%% (backref-style, backref-font, etc.) are defined in the driver
%% and store into macros; this file reads those macros.
%%
\NeedsTeXFormat{LaTeX2e}[2021/06/01]
\ProvidesPackage{codependent-render}[2026/04/11 v1.0 %
  Rendering layer for codependent backrefs]

%% ===================================================================
%% Rendering state
%% ===================================================================

% No render-side pending text is kept.  Inline emission refreshes the
% per-atom rendered cache and flushes directly from that dictionary slot.

% String constants for \ifx comparisons in rendering macros.
% Defined in codependent.sty (Section 3 options); available here
% because codependent-render.sty is loaded via \RequirePackage
% after the options block.

%% ===================================================================
%% Graph collapse
%% ===================================================================

% \codep@collapsebr{targetnum}
%   Build a comma-joined display macro \codep@br@<num> from
%   the per-target source refs.  Uses the query API
%   (\codep@graph@hasrefs, \codep@graph@foreachref) instead
%   of reading graph internals directly.  Called lazily the
%   first time \codep@render@refresh looks up <num>.
% Callback for \codep@collapsebr.  Defined at top level to avoid
% parameter-doubling issues when nested inside other macros.
%
% Resolves frozen render tokens for src-key #1 at collapse time
% (outside the accumulator's \edef) then splices them in.  The
% pre-Fix-2 form stored \noexpand\codep@brhyper{#1} — a deferred
% reference to a macro whose body is non-expandable
% (\codep@graph@getdisplay uses \def/\let, incompatible with \edef).
% Deferred storage violated the P05a contract "arg 3 carries a
% literal rendered token string with no deferred macro refs" and
% left the .aux payload fragile across passes.  Mirrors the
% hyperref-detection switch built into \codep@brhyper
% (codependent-render.sty :347 no-hyper, :355 hyper) via call-site
% \@ifpackageloaded: \codep@anchor@<key> csnames ARE populated
% from \newlabel's 4th field even without hyperref loaded, so a
% pure anchor-present check would produce \hyperlink tokens that
% crash at typeset time when hyperref is absent.
%% @utility
% \codep@collapsebr@cb@emit{src-key}
%   Build the rendered source-token entry for src-key (display +
%   optional hyperlink wrapper) and append it to \codep@tmp@acc.
%   Pre-W04-P02 this body lived inline in \codep@collapsebr@cb;
%   it was extracted so the classifier can decide whether to emit
%   without duplicating the renderer logic.
\def\codep@collapsebr@cb@emit#1{%
  \codep@graph@getdisplay{#1}{\codep@tmp@brdisplay}%
  \@ifpackageloaded{hyperref}{%
    \codep@graph@getanchor{#1}{\codep@tmp@branchor}%
    \ifx\codep@tmp@branchor\@empty%
      \let\codep@tmp@cbentry\codep@tmp@brdisplay%
    \else%
      \edef\codep@tmp@cbentry{%
        \noexpand\hyperlink%
          {\codep@tmp@branchor}{\codep@tmp@brdisplay}}%
    \fi%
  }{%
    \let\codep@tmp@cbentry\codep@tmp@brdisplay%
  }%
  \ifx\codep@tmp@acc\@empty%
    \edef\codep@tmp@acc{%
      \unexpanded\expandafter{\codep@tmp@cbentry}}%
  \else%
    \edef\codep@tmp@acc{%
      \unexpanded\expandafter{\codep@tmp@acc}, %
      \unexpanded\expandafter{\codep@tmp@cbentry}}%
  \fi%
}%

%% @behavior B-EDGE-EMPTY-PROOF
%% @utility
% \codep@collapsebr@cb{src-key}
%   Classifier-front collapse callback.  Decides whether the source
%   should appear in the rendered source-token list for the current
%   target, then dispatches to \codep@collapsebr@cb@emit.
%
%   Classification consults the W04-P01 keymap (CLASSIFICATION ONLY —
%   the keymap-resolved key is used to look up entity@<key>@parent;
%   the original src-key is still passed to the emitter so display
%   rendering remains a function of the key as the graph stored it).
%
%   Suppression rule (B-EDGE-EMPTY-PROOF / W04-P02): a proof with
%   no parent is STANDALONE — its key is "proof:a<N>" (opaque) and
%   no entity@<key>@parent record exists.  STANDALONE proofs are
%   omitted from inline source-token output.  ADJACENT proofs
%   (parent set by \codep@proof@adjacent → bindproofparent) and
%   REBOUND proofs (parent set by \codep@proofof@resolve) carry a
%   non-empty parent and are emitted normally.
\def\codep@collapsebr@cb#1{%
  \codep@graph@resolvekey{#1}\codep@tmp@cbresolved%
  \codep@graph@getkind{\codep@tmp@cbresolved}{\codep@tmp@cbkind}%
  \ifx\codep@tmp@cbkind\codep@const@typeproof%
    \codep@graph@getentityparent{\codep@tmp@cbresolved}%
      {\codep@tmp@cbparent}%
    \ifx\codep@tmp@cbparent\@empty%
      % standalone — suppress from source-token output.
    \else%
      \codep@collapsebr@cb@emit{#1}%
    \fi%
  \else%
    \codep@collapsebr@cb@emit{#1}%
  \fi%
}%
%% @implements \codep@render@refresh
\def\codep@collapsebr#1{%
  \begingroup%
    \def\codep@tmp@acc{}%
    \codep@graph@foreachref{#1}{\codep@collapsebr@cb}%
    \ifx\codep@tmp@acc\@empty%
      \global\cslet{codep@br@#1}\@empty%
    \else%
      \global\cslet{codep@br@#1}\codep@tmp@acc%
    \fi%
  \endgroup%
}

%% ===================================================================
%% Backref refresh
%% ===================================================================

% \codep@render@refresh{atomnumber}
%   Look up back-refs for the given atom and refresh its rendered cache.
%   Lazily materialises \codep@br@#1 via \codep@collapsebr
%   (§8a.3), which walks the per-target linked-list nodes built
%   from \codep@atomref aux records.  Collapse is idempotent, so
%   calling it unconditionally is fine.
%   SAFE-TO-REINVOKE, NOT IDEMPOTENT: source refs for a key may grow
%   between calls in a single run (notably joint-proof attribution);
%   the last refresh writes the complete rendered token list.
%% @behavior B-DISP-THM
%% @behavior B-PASS-ONE
\def\codep@render@refresh#1{%
  \ifbool{codep@backrefs}{%
    \codep@collapsebr{#1}%
    % After collapse, codep@br@#1 is either \@empty (no refs)
    % or a macro whose body is the comma-joined pre-rendered
    % token string (display text, or \hyperlink{anchor}{display}
    % wrappers when hyperref is loaded — produced by
    % collapsebr@cb's anchor+display lookup at collapse time).
    % \ifcsundef cannot distinguish \@empty from real data
    % (collapsebr always defines the csname), so use \ifcsempty
    % for the empty-macro test.
    \ifcsempty{codep@br@#1}{%
      % No refs to this target (collapsed to \@empty): clear cache.
      % Replay-guarded: atom may re-populate refs in same run,
      % so cache must be cleared outside replay depth to allow
      % fresh collapse on next refresh call.
      \ifnum\codep@replaydepth=0\relax%
        \csgundef{codep@rendered@#1}%
        \csgundef{codep@rlflag@#1}%
      \fi%
    }{%
      % P05a Moment 1: freeze the collapsed payload into
      % \codep@rendered@<key>, and mark the atom "touched this
      % run" via \codep@rlflag@<key> so the enddoc walker knows
      % this cache line is current-run evidence (GPT MAJOR #1
      % "stale cache clear" — touched-set semantics).
      % Fires for both inline and appendix modes (collapse ran
      % regardless of mode).  Collapse already resolved anchor and
      % display at its own call site, so the stored tokens are literal
      % rendered tokens — no deferred \codep@brhyper refs.
      % Replay-guarded: restatable replays must not
      % overwrite the cache with redundant rewrites.
      %
      % The \expandafter\expandafter\expandafter chain resolves
      % \codep@br@<key> ONE step (pulling out its rendered-token
      % body) before \unexpanded freezes them.  A single
      % \expandafter would leave the csname reference itself in
      % the xdef body, which would defeat the freeze (next-run
      % replay has no \codep@br@<key> binding).
      \ifnum\codep@replaydepth=0\relax%
        \csxdef{codep@rendered@#1}{%
          \expandafter\expandafter\expandafter\unexpanded%
          \expandafter\expandafter\expandafter{%
            \csname codep@br@#1\endcsname}}%
        \csgdef{codep@rlflag@#1}{}%
      \fi%
    }%
  }{}%
}

%% ===================================================================
%% Backref flush
%% ===================================================================

% \codep@render@flushbackref{atomnumber}
%   Emit the refreshed back-reference cache for the given atom.
%% @behavior B-DISP-THM
\def\codep@render@flushbackref#1{%
  \ifboolexpr{bool {codep@backrefs} and not bool {codep@appendix}}{%
    \ifcsdef{codep@rendered@#1}{%
      \letcs\codep@tmp@flushed{codep@rendered@#1}%
      \ifx\codep@tmp@flushed\@empty\else
        \codep@renderbackref{\codep@tmp@flushed}%
      \fi
    }{}%
  }{}%
}

%% ===================================================================
%% Rendering primitives
%% ===================================================================

% \codep@formatusedin{reflist}
%   Shared formatting helper for "Used in" lines.  Both the
%   inline path (\codep@renderbackref) and the deferred
%   paragraph path (\vadjust pre in \codep@installparahook)
%   call this, so overriding it changes ALL rendering.
%   Reads font/prefix/label from \codepsetup configuration.
%% @implements \codep@renderbackref
\newcommand*{\codep@formatusedin}[1]{%
  {\normalfont\codep@backreffont%
   \codep@applycolor{\codep@backrefprefix\codep@backreflabel\space#1.}}}
% \codep@applycolor{text}
%   Wrap text in \textcolor if backref-color is set and a
%   color package (xcolor or color) is loaded.  Falls back
%   to plain text if \textcolor is unavailable.
%% @implements \codep@renderbackref
\newcommand*{\codep@applycolor}[1]{%
  \ifx\codep@backrefcolor\@empty%
    #1%
  \else
    \ifcsundef{textcolor}{#1}{\textcolor{\codep@backrefcolor}{#1}}%
  \fi}

% \codep@renderbackref{reflist}
%   Render "Used in X, Y." inline at the end of the current atom.
%   Used for theorem/definition/lemma atoms (non-paragraph).  Flush
%   happens from cmd/end#1/before (hmode, before endmark) or from
%   \codepbackrefs (user-driven placement).
%% @behavior B-DISP-THM
%% @behavior B-REND-INLINE
\newcommand*{\codep@renderbackref}[1]{%
  % After display math the hlist is empty (\lastnodetype=-1);
  % after text/inline-math it holds character/math nodes.
  % Add the 0.5em gap only when there is preceding content,
  % so "Used in" sits flush-left when it falls on its own line.
  %
  % The cmd/end#1/before hook evaluates conditionals during
  % hook expansion, NOT at typesetting time.  Mode tests
  % (\ifvmode, \lastnodetype) return wrong values during hook
  % expansion.  We defer the spacing conditional to typesetting
  % time via \toks@: TeX inserts the tokens unexpanded, and the
  % \ifvmode / \lastnodetype checks fire when TeX processes them
  % in the env body.
  \def\codep@inline@arg{#1}%
  \toks@{%
    \ifvmode%
      \noindent%
    \else
      \ifnum\lastnodetype<\z@%
        % Hmode but the horizontal list is empty (typical after
        % display math).  A \parindent-width indent box may or
        % may not be present; neutralise it by ending the
        % current paragraph and starting fresh with \noindent.
        \par\nobreak\noindent%
      \else
        \unskip\hspace{0.5em}%
      \fi
    \fi
    \expandafter\codep@formatusedin\expandafter{\codep@inline@arg}%
  }%
  \the\toks@%
}

% \codep@emitmargin{number}
%   Typeset a superscript atom number in the left margin.
%% @behavior B-NUM-PARA
\newcommand*{\codep@emitmargin}[1]{%
  \leavevmode%
  \smash{%
    \llap{%
      {\codep@marginfont\textsuperscript{#1}\kern0.5em}%
    }%
  }%
}

%% ===================================================================
%% Appendix rendering
%% ===================================================================

% \codepappendix
%   Typeset the dependency index (appendix mode only).
%   Walks the atom array (populated at each atom site) and
%   emits an entry for every atom that has at least one
%   back-reference.  Emits section headers (via
%   \codep@appendixsection) when the section number changes
%   between consecutive atoms, using titles captured from
%   \addcontentsline during the document body.
%% @behavior B-REND-APPENDIX
%% @behavior B-LINK-APPENDIX-BIDIR
\renewcommand*{\codepappendix}{%
  \ifbool{codep@appendix}{%
    \codep@withsuppression{%
      \section*{Dependency Index}%
      \begingroup
        \small%
        \def\codep@appendix@lastsec{}%
        \count@=\z@%
        \loop%
          \ifnum\count@<\codep@atomcount%
          \advance\count@ by 1\relax
          % Check for section change and emit header if needed.
          \edef\codep@appendix@thissec{%
            \csname codep@atom@sec@\the\count@\endcsname}%
          \ifx\codep@appendix@thissec\codep@appendix@lastsec%
          \else
            \ifx\codep@appendix@thissec\@empty\else
              \edef\codep@appendix@thistitle{%
                \csname codep@sectitle@%
                  \codep@appendix@thissec\endcsname}%
              \ifx\codep@appendix@thistitle\relax\else
                \codep@appendixsection%
                  {\codep@appendix@thissec}%
                  {\codep@appendix@thistitle}%
              \fi
            \fi
            \let\codep@appendix@lastsec%
              \codep@appendix@thissec%
          \fi
          \expandafter\expandafter\expandafter%
            \codep@appendix@emit%
            \csname codep@atom@\the\count@\endcsname%
        \repeat%
      \endgroup
    }%
  }{%
    \PackageWarning{codependent}{%
      \string\codepappendix\space ignored: %
      backrefs mode is not 'appendix'}%
  }%
}

%% @implements \codepappendix
% \codep@appendix@titlecase{text}
%   Identity helper. Kept for call-site compatibility with the appendix entry
%   renderer (:425). The capture layer now stores the user-declared display
%   name in slot #4 (see B-PRINTKIND-DISPLAY-NAME), so renderer-side casing
%   is unnecessary and would corrupt macro tokens.
\def\codep@appendix@titlecase#1{#1}%

% \codep@appendixdisplay@splitenv <entity-key>:\codep@stop
%   Capture the environment prefix before the first colon in an entity key.
%% @implements \codep@appendixdisplay@resolve
\def\codep@appendixdisplay@splitenv#1:#2\codep@stop{%
  \def\codep@tmp@appendixdisplay@env{#1}%
}%

% \codep@appendixdisplay@resolve{entity-key}{captured-macro}{out-macro}
%   Resolve the appendix-rendered print kind from a per-env override map,
%   falling back to the captured entitymeta print-kind macro.
%% @behavior B-PRINTKIND-DISPLAY-OVERRIDE
\def\codep@appendixdisplay@resolve#1#2#3{%
  \expandafter\codep@appendixdisplay@splitenv#1:\codep@stop%
  \ifcsdef{codep@appendixdisplay@\codep@tmp@appendixdisplay@env}{%
    \letcs#3{codep@appendixdisplay@\codep@tmp@appendixdisplay@env}%
  }{%
    \let#3#2%
  }%
}%

% \codep@appendix@emit{prefixedkey}{type}
%   Emit an appendix entry if P05a's frozen render cache has a
%   populated payload for this atom.  Reads the entity display,
%   print-kind, and start page from the query API, and payload from
%   the P05a Moment-1/Moment-3 cache (\codep@rendered@<key>).
%% @implements \codepappendix
\def\codep@appendix@emit#1#2{%
  \ifcsdef{codep@rendered@#1}{%
    \ifcsempty{codep@rendered@#1}{%
    }{%
      \letcs\codep@tmp@rlpayload{codep@rendered@#1}%
      \codep@graph@getentitydisplay{#1}{\codep@tmp@display}%
      \codep@graph@getprintkind{#1}{\codep@tmp@printkind}%
      \codep@graph@getanchorpage{#1}{\codep@tmp@page}%
      \ifx\codep@tmp@display\@empty%
        \codep@graph@getdisplay{#1}{\codep@tmp@display}%
      \fi%
      \ifx\codep@tmp@printkind\@empty%
        \def\codep@tmp@printkind{#2}%
      \fi%
      \codep@appendixdisplay@resolve{#1}{\codep@tmp@printkind}{%
        \codep@tmp@appendixprintkind}%
      \ifx\codep@tmp@page\@empty%
        \def\codep@tmp@page{?}%
      \fi%
      \codep@appendixentry{#1}{\codep@tmp@display}{%
        \codep@tmp@appendixprintkind}{\codep@tmp@page}{\codep@tmp@rlpayload}%
    }%
  }{}%
}

% Appendix rendering helpers.
% \codep@appendixsection{number}{title}
%% @implements \codepappendix
\newcommand*{\codep@appendixsection}[2]{%
  \par\medskip\noindent%
  \textbf{#1\quad #2}\par%
}

% \codep@appendixentry{key}{display}{print-kind}{page}{reflist}
%   Emits the appendix destination codep-appendix:<key> and wraps
%   the entry label in a reverse hyperlink back to the body anchor
%   when one exists.
%% @implements \codepappendix
\newcommand*{\codep@appendixentry}[5]{%
  \par\noindent%
  \begingroup%
    \def\codep@tmp@entrylabel{%
      \codep@renderappendixpagenumtemplate{%
        \codep@appendix@titlecase{#3}~#2}{#4}}%
    \def\codep@tmp@entrycontent{\codep@tmp@entrylabel}%
    \@ifpackageloaded{hyperref}{%
      \codep@graph@getanchor{#1}{\codep@tmp@entryanchor}%
      \ifx\codep@tmp@entryanchor\@empty\else%
        \def\codep@tmp@entrycontent{%
          \hyperlink{\codep@tmp@entryanchor}{\codep@tmp@entrylabel}}%
      \fi%
      \edef\codep@tmp@appendixdestsource{#1}%
      \ifx\codep@tmp@appendixdestsource\@empty\else%
        \edef\codep@tmp@appendixdest{%
          codep-appendix:\codep@tmp@appendixdestsource}%
        \codep@emit@destination{\codep@tmp@appendixdest}%
      \fi%
    }{}%
    \hspace{1.5em}%
    \codep@tmp@entrycontent%
    \quad\dotfill\quad%
    \begin{minipage}[t]{0.45\linewidth}%
      \raggedright #5%
    \end{minipage}%
  \endgroup%
}%

%% ===================================================================
%% Hyperref link rendering
%% ===================================================================

% Hyperref link wrapping for backref numbers.
% Receives a prefixed key (e.g. theorem:2.1, equation:3.1, proof:a7).
% Default (no hyperref): render display form via query API.
% With hyperref: render display form wrapped in \hyperlink to the
% anchor retrieved via \codep@graph@getanchor.  Empty-anchor branch
% (:313) renders plain text instead of a dangling \hyperlink,
% guaranteeing every emitted link resolves to a valid destination.
%% @behavior B-LINK-CLICKABLE
%% @behavior B-LINK-NO-ORPHAN
\renewcommand*{\codep@brhyper}[1]{%
  \codep@graph@getdisplay{#1}{\codep@tmp@brdisplay}%
  \codep@tmp@brdisplay%
}

\AtBeginDocument{%
  \@ifpackageloaded{hyperref}{%
    \PackageInfo{codependent-render}{hyperref detected, enabling links}%
    \renewcommand*{\codep@brhyper}[1]{%
      \codep@graph@getanchor{#1}{\codep@tmp@branchor}%
      \codep@graph@getdisplay{#1}{\codep@tmp@brdisplay}%
      \ifx\codep@tmp@branchor\@empty%
        \codep@tmp@brdisplay%
      \else%
        \hyperlink{\codep@tmp@branchor}{\codep@tmp@brdisplay}%
      \fi}%
  }{}%
}

%% ===================================================================
%% Rendering hook activation
%% ===================================================================
%% Redefine the no-op hook points to wire them to the live
%% rendering implementations.

% \codep@render@thm@preparebackref{envname}
%   Refresh backrefs for the outermost atom and auto-flush inline.
%   Callable at cmd/end#1/before inside the tracked env body.
%   If the user already invoked \codepbackrefs inside this atom
%   (per-atom \codep@manuallyemitted@<key> flag set), the auto-flush
%   is suppressed to avoid a duplicate "Used in" line.  The flag
%   is undefined later by \codep@manuallyemitted@end@outer@clear
%   at cmd/end#1/after time.
%% @implements \codep@hooktheorem
\def\codep@render@thm@preparebackref#1{%
  \codep@subsystem@recordtotal{backref-render}%
  \ifcsdef{codep@manuallyemitted@\codep@outeratom}{%
  }{%
    \codep@render@refresh{\codep@outeratom}%
    \codep@render@flushbackref{\codep@outeratom}%
  }%
}%

% \codep@render@thm@afterend{envname}
%   Post-env hook.  Inline was already flushed in preparebackref,
%   so this is a no-op.  Retained as a hook point so the theorem
%   orchestrator body stays stable across future rendering variants.
%% @implements \codep@hooktheorem
\def\codep@render@thm@afterend#1{}%

% \codep@render@proof@end
%   Refresh and flush the proof backref cache before the proof env closes
%   (hmode, before QED).  Suppressed if the user already invoked
%   \codepbackrefs inside this proof atom (per-atom
%   \codep@manuallyemitted@<key> flag set).  Atom key derived from
%   \codep@currentproofid, which is still valid at this call site
%   (\codep@hookproof@end runs the restore AFTER this hook).
%% @implements \codep@hookproof
\def\codep@render@proof@end{%
  \codep@proof@identitykey{\codep@currentproofid}{\codep@tmp@proofkey}%
  \ifcsdef{codep@manuallyemitted@\codep@tmp@proofkey}{%
  }{%
    \codep@render@refresh{\codep@tmp@proofkey}%
    \codep@render@flushbackref{\codep@tmp@proofkey}%
  }%
}%

% \codep@render@proof@afterend
%   Post-env hook.  Inline was already flushed in proof@end,
%   so this is a no-op.  Retained as a hook point so the proof
%   orchestrator body stays stable across future rendering variants.
%% @implements \codep@hookproof
\def\codep@render@proof@afterend{}%

% \codep@render@para@emit{prefixedkey}{displaynum}
%   Emit margin label and refresh backrefs for a paragraph atom.
%% @behavior B-DISP-PARA
\def\codep@render@para@emit#1#2{%
  \codep@emitmargin{#2}%
  \codep@render@refresh{#1}%
}%

% \codep@render@manual@emit{atomkey}
%   Wired implementation of the manual-emit shim called by the
%   public \codepbackrefs macro.  Refreshes backrefs for atomkey and
%   immediately flushes them inline at the call site.  The
%   \codep@manuallyemitted@<key> flag is set by \codepbackrefs
%   BEFORE this call, so the env-end auto-flush check
%   (\codep@render@thm@preparebackref / \codep@render@proof@end)
%   sees the flag and suppresses the duplicate emission.
%% @implements \codepbackrefs
\def\codep@render@manual@emit#1{%
  \codep@render@refresh{#1}%
  \codep@render@flushbackref{#1}%
}%

\endinput